A newer version of the Gradio SDK is available: 6.22.0
title: GAIA 问答 Agent 评测
emoji: 🕵🏻♂️
colorFrom: indigo
colorTo: indigo
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480
这是 Hugging Face Agents Course Final Assignment 的基础 Space，用于运行并提交 GAIA 风格问题的 Agent 作答结果。
当前版本已经改成 LangGraph 类型工作流 Agent：
app.py会通过课程评测接口拉取问题并提交答案。agent.py中的GaiaAgent会先让 LLM 判断问题类型，再由 LangGraph 路由到对应工具节点。tools/executor.py和tools/tool_specs.py负责注册、描述并执行工具。tools/目录包含规则题、附件下载、Python 执行、Excel 计算、结构化网页、网页检索和体育数据工具。- 登录 Hugging Face 后，界面会使用当前 HF 用户名提交答案。
- 提交时会携带当前 Space 的代码仓库链接，便于评测系统记录实现来源。
Space 配置参考：https://huggingface.co/docs/hub/spaces-config-reference
本地 GAIA 测试设计
本地测试不要直接等同于官方评分。课程评分接口的 /questions 可以返回问题列表，但不会返回标准答案；带附件的问题还需要额外处理文件。因此，本地测试应该拆成两层：
- 流程测试：验证 Agent 能稳定读取问题、处理附件路径、调用工具、生成答案、记录日志，并输出符合提交接口要求的 JSON。
- 正确率测试：使用你自己维护的本地 gold 数据，或公开/可访问的 GAIA 数据子集，对 Agent 的答案做离线比对。
建议的本地目录结构：
.
├── app.py
├── agent.py
├── gaia_local_eval.py
├── tools/
│ ├── direct_rules.py
│ ├── attachment_loader.py
│ ├── code_runner.py
│ ├── spreadsheet_solver.py
│ ├── structured_web_tools.py
│ ├── sports_solver.py
│ ├── tool_specs.py
│ └── executor.py
├── data/
│ ├── questions.json
│ ├── gold_local.jsonl
│ └── attachments/
│ └── <task_id>/
│ └── <file_name>
└── runs/
└── <timestamp>.jsonl
建议的执行流程：
- 缓存题目：从
https://agents-course-unit4-scoring.hf.space/questions拉取当前题目，保存为data/questions.json，避免频繁请求接口导致限流或不稳定。 - 准备附件：如果题目有
file_name，优先尝试用裸task_id请求/files/{task_id}；如果接口不可用，就把附件手动放到data/attachments/<task_id>/下。 - 抽离 Agent：把真实作答逻辑放入
agent.py，提供统一入口，例如answer(question: str, file_path: str | None = None) -> str。 - 编写本地 runner：
gaia_local_eval.py只负责读取questions.json、定位附件、调用 Agent、保存每题的答案、耗时、错误、工具轨迹和置信度。 - 编写答案规整器：对数字、货币、日期、大小写、逗号分隔列表、空格和标点做标准化，避免因为格式差异误判。
- 维护 gold 文件：
gold_local.jsonl每行包含task_id、expected_answer、match_type和备注。没有标准答案的问题只做流程测试，不纳入正确率统计。 - 分层运行：先跑 1 到 3 道 smoke test，再跑全部本地题；确认稳定后再通过 Space 按官方流程提交。
当前代码采用 LangGraph 三段式工作流：
classify：LLM 只判断问题类型，例如direct_text、python_code、spreadsheet、wikipedia、sports、web_url、web_search、attachment_text、audio_media、video_media、vision_image、unknown。- 类型节点：LangGraph 根据问题类型调用对应工具节点，例如
direct_answer_tool、python_tool、spreadsheet_tool、wikipedia_tool、sports_tool、web_read_tool、web_search_tool。 finalize：LLM 只把工具结果格式化为题目要求的最终答案；如果 LLM 调用失败，则使用工具候选答案兜底。
分类输出格式：
{"question_type":"wikipedia","confidence":"high","reason":"Wikipedia structured table question","query":"1928 Summer Olympics athletes"}
最终答案格式：
{"answer":"CUB","confidence":"high"}
当前仍采用 40% 优先策略：为了先冲过最低分，不处理音频和视频题，只集中处理文本、网页、Python、Excel、体育统计和少量确定性规则题。
当前优先覆盖的题型：
- 反向句子题。
- 非交换表题。
- 植物学蔬菜分类题。
- Python 附件最终输出题。
- Excel 食品销售合计题。
- Mercedes Sosa Wikipedia 专辑计数题。
- Wikipedia Featured Article 恐龙提名人题。
- 1928 Summer Olympics 最少运动员 IOC 代码题。
- 1977 Yankees walks leader at-bats 题。
本地回归测试：
python3 gaia_local_eval.py
注意：现在本地回归会优先调用 LLM 做题型分类，并在最后调用 LLM 做答案格式化，因此需要 HF_TOKEN，并会消耗少量 Hugging Face Inference Providers 额度。这个 token 必须具备 Make calls to Inference Providers 权限，否则 LLM 请求会返回 403。分类失败或格式化失败时，工作流会进入兜底逻辑，尽量使用已有工具候选答案。MAX_AGENT_STEPS 可用于限制兜底阶段最多尝试的工具数。
默认不启用 response_format={"type":"json_object"}，因为 HF Router 的部分 provider 对这个参数支持不稳定，可能返回空 message.content。如果你确认当前模型/provider 支持 JSON mode，可以设置 HF_PLANNER_USE_RESPONSE_FORMAT=1 再启用。
如果本地没有安装依赖，先执行：
python3 -m pip install -r requirements.txt
如果以后要追求更高分，真实 Agent 至少应该补齐这些工具能力：
- 网页检索和网页阅读，用于维基、论文、新闻、体育数据等开放网络问题。
- Python 执行沙箱，用于数学、表格、代码题和可复现计算。
- 文件解析能力，包括图片、音频、Excel、CSV、Python 文件和普通文本。
- 音频转写能力，用于
.mp3附件。 - 视频处理能力，用于 YouTube 问题，可结合字幕、抽帧和视觉模型。
- 棋类分析能力，用于棋盘图像和最优走法题。
- 答案格式控制能力，严格输出题目要求的最终答案，不输出推理过程。
本地 runner 的目标不是替代官方评分，而是在提交前暴露三类问题：Agent 崩溃、工具链缺失、答案格式错误。最终分数仍以官方 /submit 返回结果为准。