企业官网建设流程全解析

ADK 评测集（Evaluation Sets）实战指南：为 AI Agent 编写并运行自动化评测

【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack

在基于 Google Agent Development Kit（ADK）构建 Agent 时，如何证明"Agent 真的按预期工作"是一道绕不开的关卡。本指南以 agent-starter-pack 仓库中 ADK 示例代理（agent_starter_pack/agents/adk）自带的评测集为切入点，系统讲解.evalset.json评测文件的完整格式、make eval系列命令的用法、评测指标含义，以及如何基于自己的DESIGN_SPEC.md场景快速编写可复用的自定义评测集。读完本文，你将掌握一套"定义评测案例 → 一键运行 → 解读轨迹与响应指标"的完整 Agent 评测工作流。

一、评测集（Evaluation Sets）在 ADK 中的角色

评测集是一组结构化的测试场景集合，用于回答两个问题：Agent 是否调用了正确的工具？Agent 的回答是否匹配预期？在 ADK 的项目结构中，评测集存放在tests/eval/evalsets/目录下，与评测配置eval_config.json配套使用：

• basic.evalset.json：默认评测集样例，覆盖两个典型场景（问候、天气查询）；
• eval_config.json：评测配置，定义以何种标准评判最终回答质量；
• evalsets/README.md：评测集的使用与格式说明（本文即围绕其展开）。

评测对象是 app/agent.py 中定义的root_agent，它使用gemini-3-flash-preview模型，并挂载了两个模拟工具get_weather与get_current_time。评测集里的weather_query案例（"What's the weather like in San Francisco?"）正是为了验证 Agent 是否会正确调用get_weather工具——评测集与工具能力一一对应，这是理解评测设计的关键。

二、一键运行评测：make eval 命令族

评测的运行入口封装在模板生成的 Makefile 中，从仓库的 Makefile 快照（adk_agent_engine_no_data.makefile）可以看到其完整实现：

# Run agent evaluation using ADK eval # Usage: make eval [EVALSET=tests/eval/evalsets/basic.evalset.json] [EVAL_CONFIG=tests/eval/eval_config.json] eval: uv sync --dev --extra eval uv run adk eval ./test_adk $${EVALSET:-tests/eval/evalsets/basic.evalset.json} \ $(if $(EVAL_CONFIG),--config_file_path=$(EVAL_CONFIG),$(if $(wildcard tests/eval/eval_config.json),--config_file_path=tests/eval/eval_config.json,)) eval-all: @for evalset in tests/eval/evalsets/*.evalset.json; do \ echo "▶ Running: $$evalset"; \ $(MAKE) eval EVALSET=$$evalset || exit 1; \ done @echo "✅ All evalsets completed"

三种典型用法如下：

# 1. 运行默认评测集（basic.evalset.json） make eval # 2. 运行指定的评测集（如自定义的 custom.evalset.json） make eval EVALSET=tests/eval/evalsets/custom.evalset.json # 3. 运行目录下全部评测集 make eval-all

几个值得注意的实现细节：

• make eval执行前会先运行uv sync --dev --extra eval，确保安装好评测所需的evalextra 依赖；
• 底层真正执行的是uv run adk eval <agent目录> <evalset路径>，其中<agent目录>是模板渲染生成的 Agent 目录（上例渲染为./test_adk，实际路径以你生成的项目为准），$${EVALSET:-...}表示未传EVALSET时回退到basic.evalset.json；
• --config_file_path参数指向tests/eval/eval_config.json；若在命令行显式传入EVAL_CONFIG，则优先使用该值，否则自动探测项目内是否已存在默认配置文件；
• eval-all通过 shell 循环遍历tests/eval/evalsets/*.evalset.json，逐个执行make eval EVALSET=...，任一评测集失败即中断（|| exit 1）。

三、Evalset 格式详解：从根字段到单条用例

每个.evalset.json都遵循 ADK 评测的标准 JSON 结构。以仓库自带的 basic.evalset.json 为例，其完整内容为：

{ "eval_set_id": "basic_eval", "name": "Basic Agent Evaluation", "description": "Sample evaluation set for testing core agent functionality. Customize these cases based on your DESIGN_SPEC.md.", "eval_cases": [ { "eval_id": "greeting", "conversation": [ { "user_content": { "parts": [{"text": "Hello, what can you help me with?"}] } } ], "session_input": { "app_name": "app", "user_id": "eval_user", "state": {} } }, { "eval_id": "weather_query", "conversation": [ { "user_content": { "parts": [{"text": "What's the weather like in San Francisco?"}] } } ], "session_input": { "app_name": "app", "user_id": "eval_user", "state": {} } } ] }

与之对照，README 中给出的通用格式骨架如下：

{ "eval_set_id": "unique_id", "name": "Human-readable name", "description": "What this evalset tests", "eval_cases": [ { "eval_id": "case_id", "conversation": [ { "user_content": { "parts": [{"text": "User message"}] }, "intermediate_data": { "tool_uses": [ {"name": "tool_name", "args": {"param": "value"}} ] } } ], "session_input": { "app_name": "app_name", "user_id": "test_user", "state": {} } } ] }

顶层字段

单条用例字段

conversation 内部的细节

• user_content.parts[].text：本轮用户输入的文本内容。parts是 ADK 内容分片结构，可在text之外扩展其他类型的消息分片；
• intermediate_data.tool_uses：期望的工具调用（可选）。每条记录包含name（期望调用的工具名）与args（期望传入的参数）。这一字段用于轨迹匹配（trajectory matching），即校验 Agent 在实际运行中是否按期望调用了工具、参数是否正确。

session_input 的关键约束

app_name必须与 Agent 应用名保持一致。在 app/agent.py 中，应用通过App(root_agent=root_agent, name="{{cookiecutter.agent_directory}}")注册；basic.evalset.json 中填写的是"app"，两者需对应，否则评测运行时会话路由失败。state用于注入初始对话/上下文状态，无额外状态时保留为空对象{}。

四、评测指标：轨迹匹配与响应质量

ADK eval 输出两类核心指标：

• tool_trajectory_avg_score（工具轨迹平均分）：评判 Agent 是否正确、按正确顺序调用了工具。该指标依赖intermediate_data.tool_uses提供期望轨迹——如果评测用例没有声明期望的工具调用，轨迹维度自然无法评估。对于具备工具调用能力的 Agent（如get_weather/get_current_time），这一指标是"能力测试"的关键；
• response_match_score（响应匹配分）：衡量 Agent 最终回答与期望输出之间的相似度，适用于校验回答内容本身的正确性（如问候语、信息准确性）。

当默认的两个指标无法满足质量要求时，仓库还提供了基于裁判模型（judge model）的评分标准（criteria）机制。eval_config.json 中定义了一个完整的 rubric 评测标准：

{ "criteria": { "rubric_based_final_response_quality_v1": { "threshold": 0.8, "judgeModelOptions": { "judgeModel": "gemini-3-flash-preview", "numSamples": 1 }, "rubrics": [ { "rubricId": "relevance", "rubricContent": { "textProperty": "The response directly addresses the user's query." } }, { "rubricId": "helpfulness", "rubricContent": { "textProperty": "The response is helpful and provides useful information." } } ] } } }

该配置的解读：

• threshold: 0.8：通过阈值设为 0.8，即最终回答的 rubric 平均分须不低于 0.8 才算通过；
• judgeModelOptions.judgeModel: "gemini-3-flash-preview"：由指定的 Gemini 模型充当裁判，对回答打分（与 agent.py 中 Agent 使用的模型一致）；
• judgeModelOptions.numSamples: 1：每个用例采样 1 次，兼顾运行成本与稳定性；
• rubrics：逐条列出评判维度，每条含rubricId（如relevance、helpfulness）与rubricContent.textProperty（该维度的人类可读评判准则）。可将此视为"自定义维度 + 评分阈值"的质检清单。

五、创建自定义 Evalset 的实战步骤

按 README 给出的流程，结合仓库代码可以整理出完整的实操路径：

第 1 步：复制模板。以 basic.evalset.json 为蓝本，复制为tests/eval/evalsets/custom.evalset.json，并修改eval_set_id、name、description使其描述你的场景。

第 2 步：围绕 DESIGN_SPEC.md 场景添加用例。每个核心场景对应一条eval_cases条目。针对本仓库的示例 Agent，app/agent.py 提供了get_weather（模拟旧金山天气）与get_current_time（模拟旧金山时间）两个工具，可据此设计用例：查询天气、查询时间、以及"无法识别城市"的边界情况。

第 3 步：为能力测试声明期望工具调用。若某条用例期望 Agent 调用工具，应在对应轮次补上intermediate_data.tool_uses，使轨迹指标可被评估。例如天气用例可声明期望调用get_weather：

{ "eval_id": "weather_query", "conversation": [ { "user_content": { "parts": [{"text": "What's the weather like in San Francisco?"}] }, "intermediate_data": { "tool_uses": [ {"name": "get_weather", "args": {"query": "San Francisco"}} ] } } ], "session_input": { "app_name": "app", "user_id": "eval_user", "state": {} } }

第 4 步：运行并迭代。执行make eval EVALSET=tests/eval/evalsets/custom.evalset.json（或直接make eval EVALSET=your_evalset.json的等价形式）运行新评测集，根据轨迹分与响应分调整用例或 Agent 行为。全部完成后可用make eval-all一次性回归所有评测集。

六、评测集设计的最佳实践

README 给出了四条可操作性很强的建议，结合仓库实践可进一步展开：

1. 以 3～5 条代表性用例起步：覆盖最核心的对话路径即可，避免评测集膨胀带来运行成本。basic.evalset.json的 2 条用例（问候 + 天气查询）就是"最小可用"的示范；
2. 同时包含正常路径与边界用例（happy path & edge cases）：不仅测"正确调用工具"，还要测"无法回答/无匹配工具"时的兜底行为。例如get_current_time对未收录城市会返回 "Sorry, I don't have timezone information..."（见 agent.py），这类分支同样值得固化为评测用例；
3. 覆盖 DESIGN_SPEC.md 中的每个核心能力：能力与评测一一对应，避免"上线了才发现某能力从未被验证"；
4. 在生产中发现 bug 时及时补充用例：把线上回归沉淀为评测集，形成"发现即固化"的持续改进闭环。

七、评测与测试体系的配合

评测集并不是孤立的。在同目录的 tests/integration/test_agent.py 中，可以看到另一种验证手段：直接用InMemorySessionService创建会话、用Runner以 SSE 流式模式运行root_agent，断言事件流中存在文本内容。它与adk eval的分工在于：

• 集成测试：断言"Agent 能跑通、有输出"，偏功能正确性，速度快、依赖轻（无模型裁判）；
• 评测集：断言"Agent 输出质量达标、轨迹正确"，偏行为质量，通过轨迹指标与 rubric 标准做量化评估。

两者互为补充：集成测试把守"能不能跑"的底线，评测集度量"跑得好不好"。若需要更深入的 Agent 评估能力（如自定义轨迹指标、响应质量雷达图、按指标维度可视化对比），仓库还提供了 evaluating_adk_agent.ipynb 作为进阶参考，可用于在原型阶段到生产部署后持续评估 Agent 表现。

结语

评测集是 Agent 从"能演示"走向"可上线"的质检基石。通过make eval一键运行、.evalset.json结构化定义场景、轨迹与响应双指标量化结果，再加上 rubric 裁判标准的自定义扩展，你可以把对 Agent 的信任从"感觉还行"升级为"指标通过"。从复制basic.evalset.json开始，把 DESIGN_SPEC.md 中的每个场景固化下来，并在生产问题的反馈中不断补充用例，一套可持续演进的 Agent 质量保障体系便由此建立。

【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack