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

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 KitADK构建 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案例Whats 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 [EVALSETtests/eval/evalsets/basic.evalset.json] [EVAL_CONFIGtests/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_pathtests/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 EVALSETtests/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: Whats 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: {} } } ] }顶层字段字段类型说明eval_set_idstring评测集的唯一标识如basic_eval用于区分不同评测集namestring人类可读的评测集名称便于在评测报告中识别descriptionstring说明该评测集要验证什么能力建议直接描述测试 Agent 的哪些核心功能eval_casesarray测试场景数组每个元素是一条独立的评测用例单条用例字段字段类型说明eval_idstring用例的唯一 ID如greeting、weather_query用于在结果中定位具体用例conversationarray用户消息序列。ADK 支持多轮对话式评测序列中的每个元素代表一轮消息session_inputobject初始会话状态包含app_name、user_id与stateconversation 内部的细节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_agentroot_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 users 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条目。针对本仓库的示例 Agentapp/agent.py 提供了get_weather模拟旧金山天气与get_current_time模拟旧金山时间两个工具可据此设计用例查询天气、查询时间、以及无法识别城市的边界情况。第 3 步为能力测试声明期望工具调用。若某条用例期望 Agent 调用工具应在对应轮次补上intermediate_data.tool_uses使轨迹指标可被评估。例如天气用例可声明期望调用get_weather{ eval_id: weather_query, conversation: [ { user_content: { parts: [{text: Whats 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 EVALSETtests/eval/evalsets/custom.evalset.json或直接make eval EVALSETyour_evalset.json的等价形式运行新评测集根据轨迹分与响应分调整用例或 Agent 行为。全部完成后可用make eval-all一次性回归所有评测集。六、评测集设计的最佳实践README 给出了四条可操作性很强的建议结合仓库实践可进一步展开以 35 条代表性用例起步覆盖最核心的对话路径即可避免评测集膨胀带来运行成本。basic.evalset.json的 2 条用例问候 天气查询就是最小可用的示范同时包含正常路径与边界用例happy path edge cases不仅测正确调用工具还要测无法回答/无匹配工具时的兜底行为。例如get_current_time对未收录城市会返回 Sorry, I dont have timezone information...见 agent.py这类分支同样值得固化为评测用例覆盖 DESIGN_SPEC.md 中的每个核心能力能力与评测一一对应避免上线了才发现某能力从未被验证在生产中发现 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考