内容
<div align="center">
<img src="media/shots/home.png" alt="GAFFER · 为世界杯提供一切服务。没有任何虚假信息。" width="100%">
# ⚽ GAFFER
### 捕获并纠正自身错误的主动智能体
**它在Arize Phoenix中为每个答案进行GOAL或MISS的评判，当它出错时自我训练，并证明这一点，我们甚至对评估者进行了评分。其应用场景：世界杯。为比赛提供一切服务，没有任何虚假信息。**
[](https://gaffer-734868402447.us-central1.run.app)
[](https://www.youtube.com/watch?v=ARjeNECEABY)
</div>
> 为 **Google Cloud Rapid Agent Hackathon · Arize track** 构建。 一个FIFA世界杯2026的球迷礼宾服务，通过观看比赛实时优化，因为其教练也是一个智能体，其分析室是Arize Phoenix。
---
## 问题
任何聊天机器人都可以告诉你谁正在比赛。但是，当你询问那些真正决定是否能参加世界杯的问题时，它就崩溃了：*我可以带着这个包通过安检吗？哪辆确切的火车能到达门口？过境时我需要什么证件？* 普通的AI会立即流利地回答这些问题，但往往是错误的，而你只有在关口检查时才知道。自信地给出错误答案是最糟糕的失败模式，因为没有人会质疑一个听起来很有把握的答案。
**GAFFER正是为这些问题而构建的，它拒绝胡编乱造。**
<div align="center">
<img src="media/shots/ask.png" alt="一个有根据、有来源的答案" width="88%">
<br><em>一个复杂、多部分的提问，从验证记录中得到答案：确切的铁路路线、4小时的宾夕法尼亚车站限制、40,000名乘客的105美元票价上限、行李尺寸。每个事实都有其来源。</em>
</div>
---
## 工作原理：循环
GAFFER有两个智能体和一个裁判，构成一个封闭的自我改进循环。足球框架是其架构。
**🥅 球员** 回答球迷的问题（体育场、赛程、政策、旅行），基于一个经过验证的知识库，并通过OpenInference跟踪到Phoenix。 其工具在找不到事实时返回显式的`NOT_FOUND` ，这使得系统可以区分**有根据的** 和 **猜测的**。
**🟨 裁判** 是一个Gemini LLM裁判，对每个答案进行实时评分，`GOAL` 或 `MISS` ，并将判决结果记录为该确切跟踪的跨度注释。只有具体事实必须得到支持；诚实的犹豫和标注的指导通过。
**📋 教练** 是教练。它通过 **Phoenix MCP服务器** 审查比赛录像：拉取失败的跟踪，命名失败模式，将每个错误钻入回归数据集（`training-ground-wc26`），重写比赛规则，并运行 **演练** ，两个Phoenix实验，旧提示与新提示，由裁判评分。
**🏆 晋升以证据为依据。** 候选比赛规则只有在击败生产版本时才会发布。球员在会话开始时从Phoenix注册表中按标签加载提示，因此 **Phoenix是部署机制，而不是仪表板。** 没有人工干预。没有重新部署。下一次问题运行在改进的比赛规则上。
<div align="center">
| 它评估自己 | 它重写自己 | 只有赢家才会被发布 |
|:---:|:---:|:---:|
| <img src="media/shots/loop_trace.png" width="100%"> | <img src="media/shots/loop_diff.png" width="100%"> | <img src="media/shots/loop_scrim.png" width="100%"> |
| 裁判对每个答案进行评分，在Phoenix中跟踪 | 教练编辑自己的提示，基于Phoenix MCP | 成对实验仅在证明获胜时发布 |
</div>
---
## 架构
```
┌────────────────────────────────────────────┐
│ ARIZE PHOENIX │
OpenInference traces │ traces · annotations · prompt registry │
┌─────────────────▶│ datasets · experiments │
│ └───────┬───────────────────▲────────────────┘
│ │ prompt by tag │ MCP (16 tools)
│ ▼ "production" │
┌─────┴──────┐ questions ┌──────────┐ ┌─────┴──────┐
│ 球迷（网页） │────────────▶│ 球员 │ │ 教练 │
│ 球场 │◀────────────│ ADK智能体│ │ ADK智能体 │
└────────────┘ 答案 │ Gemini │ │ Gemini │
▲ └────┬─────┘ └─────┬──────┘
│ GOAL/MISS判决 │ 每个答案 │ run_scrimmage()
┌─────┴───────┐ ▼ ▼
│ 裁判 │◀──────── 跨度注释 Phoenix实验：
│ LLM裁判│ 当前 vs 候选
└─────────────┘ → 仅在更好时发布
```
## 证明：循环，在Arize Phoenix中
大多数自我改进的智能体都模糊不清质量。GAFFER的质量是有审计证据的，并且在应用的 [**记分板**](https://gaffer-734868402447.us-central1.run.app/#proof) 中实时显示。这里的一切都是真实的，从Phoenix工作区中提取：
- **21轮演练。12次晋级，9次拒绝。** 在21轮中，生产比赛规则从裁判评分 **0.20提升到0.95** ，在它对抗的回归集上（下一个强化步骤是密封的保留）。智能体仅在候选人击败生产版本时才会发布候选版本，拒绝了其他版本，包括最近的一轮（生产版本`0.95`击败`0.70`的候选版本，没有发布）。从一个回合到另一个回合的个别增益大多在噪音范围内，只有12次发布中的1次清除了一个配对的bootstrap地板，因此趋势是信号，而不是任何单一步骤。
- **44个实验，25个比赛规则版本** ，每次`production`标签由教练自己移动，基于获胜的实验。可以早早得分`MISS 0.00`的问题（体育场铁路通道，休斯顿天气，电源银行规则）现在得分`GOAL 1.00`。
<table>
<tr>
<td width="50%"><img src="docs/media/phoenix/04-experiments-curve.png" alt="44个实验攀升"><br><sub><b>44个实验，攀升。</b> 在<code>training-ground-wc26</code>上每次演练的裁判得分。</sub></td>
<td width="50%"><img src="docs/media/phoenix/06-prompt-registry-versions.png" alt="25个比赛规则版本"><br><sub><b>25个比赛规则版本。</b> Phoenix提示注册表； v25携带<code>production</code>标签，玩家在会话开始时加载。</sub></td>
</tr>
<tr>
<td width="50%"><img src="docs/media/phoenix/01-trace-waterfall-annotation.png" alt="裁判注释跟踪"><br><sub><b>裁判在跟踪。</b> 每个答案都是一个跨度；裁判提交一个GOAL/MISS注释，带有分数和解释。</sub></td>
<td width="50%"><img src="docs/media/phoenix/08-project-spans-goalmiss.png" alt="GOAL/MISS在实时跟踪中"><br><sub><b>实时评分。</b> 球员生产跟踪中的实时GOAL/MISS分数，从μ1.00到μ0.20。</sub></td>
</tr>
</table>
---
## 行程规划器
除了聊天外，GAFFER还计划整个行程。添加您想要参加的比赛，它会构建一个有根据的行程，包括场地、交通到门口、球迷节日和天气，并对每个比赛进行不确定性标记。然后将其交给裁判进行压力测试，实时进行。
<div align="center">
<img src="media/shots/matches_plan.png" alt="一个有根据的多城市行程计划" width="88%">
</div>
---
## 技术栈
| 层 | 内容 |
|---|---|
| **智能体** | Google ADK · Gemini 3.5 Flash（球员）+ Gemini 2.5 Flash（裁判）on Vertex AI |
| **可观察性 + 控制循环** | Arize Phoenix Cloud: `arize-phoenix-otel` + OpenInference跟踪，跨度注释，提示注册表，数据集，实验 |
| **教练的操作** | 官方`@arizeai/phoenix-mcp`服务器（stdio，16个工具）通过ADK `McpToolset` |
| **服务** | FastAPI + Server-Sent Events · 单容器Cloud Run（Python智能体 + Node for MCP服务器） |
| **知识库** | 16个场地，所有48支球队和小组，首周比赛，FIFA球迷政策，节日，天气，交通。从主要来源验证，每个来源在[`data/sources.md`](data/sources.md)中引用 |
---
## 运行
前提条件：Python 3.11+ with [uv](https://docs.astral.sh/uv/)， **Node.js 18+** （教练通过`npx`启动Phoenix MCP服务器），具有启用Vertex AI的GCP项目（`gcloud auth application-default login`），以及免费的[Phoenix Cloud](https://app.phoenix.arize.com)帐户。
```bash
uv sync
cp .env.example .env # 添加您的GCP项目 + Phoenix Cloud密钥/端点
uv run python -m scripts.seed_playbook # 比赛规则v1 → Phoenix，标记为"production"
make dev # http://localhost:8080
```
在 **球场** 上提问。观看判决结果。然后点击 **▸ 教练会话** ，观看教练处理比赛录像，每个Phoenix MCP调用实时流式传输。部署时使用`make deploy`。
> `openai`/`anthropic`出现在`uv.lock`中，只是作为`arize-phoenix`的未使用依赖项。运行时调用的模型仅限Google（Vertex AI上的Gemini）。
---
## 适用于评委的2分钟游览
已部署的比赛规则已经被教练过，所以大多数问题都获得`GOAL`评分。要观看完整的循环实时运行：
1. 打开 [**实时应用**](https://gaffer-734868402447.us-central1.run.app) 并尝试击败球员。提出操作性和具体的提问，或偷偷带入错误的假设（*“荷兰队vs日本队的揭幕战几点开始？”*）。如果裁判提交红色`MISS`，您就有教练材料。
2. 点击 **▸ 教练会话** 。教练通过Phoenix MCP拉取比赛录像，将您的失误钻入`training-ground-wc26`，重写比赛规则，进行演练（两个Phoenix实验，裁判评分），并仅在获胜时发布。晋升横幅是回报。
3. 重新提问您的问题。标题中的比赛规则芯片显示新版本，从Phoenix注册表中按标签提供。 **没有重新部署发生。**
---
## 为什么这在足球之外很重要
将知识库和球员替换，GAFFER就可以成为任何面向客户的智能体。循环，*跟踪 → 裁判 → 钻取 → 重写 → 实验 → 有条件的发布*，是生产智能体应该如何发布提示更改的方式：像代码一样，通过CI。我们刚刚让CI智能体化。
---
<div align="center">
**[⚽ 尝试GAFFER](https://gaffer-734868402447.us-central1.run.app)** · MIT许可
<sub>为Google Cloud Rapid Agent Hackathon粉丝制作。不隶属于FIFA，不赞助或认可。</sub>
</div>
