ADK 代理评估集Evalset实战指南用adk eval系统验证 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导读本文围绕 agent-starter-pack 中 ADK with Agent2AgentA2A示例模板的评估体系展开系统讲解 Evaluation Sets评估集的标准 JSON 格式、make eval/make eval-all运行机制、核心评估指标工具轨迹匹配与响应匹配并结合仓库源码与真实配置说明如何设计、编写和维护自定义 evalset。读完本文你将掌握一套用 evalset 固化 Agent 能力验收标准的实操方案能够把每次工具调用是否准确、响应是否达标变成可量化、可回归的自动化检查。一、评估集在 Agent 工程化中的定位在 agent-starter-pack 中每个 ADK 模板的生成项目都会内置一套tests/eval/evalsets/目录用于通过adk eval验证 Agent 行为。以agent_starter_pack/agents/adk_a2a为例评估体系由两部分组成evalset评估集定义要测什么即一组带期望结果的测试场景存放在tests/eval/evalsets/下以.evalset.json结尾eval_config评估配置定义怎么打分存放评分标准与判分模型默认文件为tests/eval/eval_config.json。两者配合的意义在于Agent 是概率性的 LLM 应用单纯能跑通不等于行为正确。通过预先写下给定用户消息Agent 应当调用哪些工具、按什么顺序调用、最终给出什么样的响应开发者可以在每次改动工具或提示词后一键回归防止能力退化。二、运行评估三条 Makefile 命令该模板通过根目录 Makefile 暴露了三条评估入口# 运行默认 evalsettests/eval/evalsets/basic.evalset.json make eval # 运行指定的 evalset make eval EVALSETtests/eval/evalsets/custom.evalset.json # 运行 tests/eval/evalsets/ 目录下所有 evalset make eval-all2.1make eval的底层实现从 Makefile 源码可以看到make eval实际执行的是eval: uv sync --dev --extra eval uv run adk eval ./{{cookiecutter.agent_directory}} $${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,))其中几个关键点uv sync --dev --extra eval先安装带eval额外依赖的开发环境确保adk eval所需的评估组件就绪$${EVALSET:-tests/eval/evalsets/basic.evalset.json}若未显式传EVALSET则回退到默认的basic.evalset.json。注意 Makefile 中使用$$将变量转义交给 shell 展开因此也可以在命令行直接覆盖--config_file_path若传入EVAL_CONFIG则优先使用否则自动探测项目下是否存在默认的tests/eval/eval_config.json传给adk eval的第一个参数是 Agent 目录此处为生成的 agent 目录adk eval会加载其中的agent.py定义的根 Agent 执行用例。2.2make eval-all的批量执行Makefile 中的eval-all遍历tests/eval/evalsets/*.evalset.json逐个调用make eval EVALSET$$evalset任一 evalset 失败即exit 1中断整个流程全部通过后输出完成提示。这意味着每个能力域可以拆成独立 evalset 文件如chat.evalset.json、tools.evalset.jsonmake eval-all一键全量回归。2.3 评估结果输出adk eval运行后会针对每个 eval case 给出评分与详情包含工具调用轨迹的匹配情况、最终响应的匹配度以及基于eval_config.json中 rubric 的打分明细。开发者在本地迭代 Agent 时应把make eval作为与make test同等重要的质量门禁。三、Evalset 标准格式详解每个.evalset.json遵循 ADK 评估格式标准骨架如下{ 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: {} } } ] }3.1 顶层字段字段类型说明eval_set_idstring评估集的唯一标识建议与文件名一致如basic_evalnamestring人类可读的名称用于在评估报告中标识该评估集descriptionstring描述该评估集覆盖的行为范围与测试意图eval_casesarray测试场景数组每个元素是一次独立的评估用例3.2 用例字段eval_cases 元素字段类型说明eval_idstring用例唯一标识如greeting用于在结果中定位到具体场景conversationarray对话序列依次描述用户输入与期望的中间过程工具调用session_inputobject会话初始状态含app_name、user_id与state3.3 conversation 内部结构user_content用户消息内容parts[].text为实际发送给 Agent 的文本即测试输入intermediate_data.tool_uses期望的工具调用轨迹。name为工具名args为期望的参数对象。此字段用于轨迹匹配trajectory matching即验证 Agent 是否在正确的位置调用了正确的工具session_input提供会话上下文。其中app_name应与 Agent 应用名对应user_id标识测试用户state可放置需要预置的会话状态。四、仓库自带的 basic.evalset.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: capability_query, conversation: [ { user_content: { parts: [{text: What tools do you have available?}] } } ], session_input: { app_name: app, user_id: eval_user, state: {} } } ] }两个用例分别覆盖问候与能力询问两类无工具调用的纯对话场景因此 conversation 中只包含user_content未声明intermediate_data.tool_uses。这与示例 Agentapp/agent.py的定义相吻合——它注册了get_weather、get_current_time、request_user_input三个工具但基础的问候场景不需要调用任何工具。需要特别强调的是该文件顶部的 description 明确指出这些用例只是示例应基于项目的DESIGN_SPEC.md中定义的能力清单进行定制。五、评估指标Agent 行为如何被量化adk eval输出两类核心指标tool_trajectory_avg_score衡量是否正确、是否按顺序调用了工具。Agent 在多轮对话中形成的工具调用序列称为轨迹trajectory该指标将实际轨迹与intermediate_data.tool_uses中声明的期望轨迹进行匹配response_match_score衡量响应与期望输出的相似度用于判断最终回复是否达到预期。5.1 轨迹指标的细分关于轨迹评估的细节可以参考同目录下的 evaluating_adk_agent.ipynb其中给出了 Vertex AI Gen AI Evaluation 语境下更细分的轨迹指标语义可迁移到adk eval的轨迹匹配理解上exact match实际轨迹与期望轨迹完全一致工具与顺序都相同in-order match期望轨迹中的工具调用都出现在实际轨迹中且顺序一致允许存在额外调用any-order match期望轨迹中的工具调用都出现即可不关心顺序与额外调用precision / recall按比例衡量实际轨迹与期望轨迹的重合程度取值 0~1。这意味着轨迹评分并非简单的对/错二分而是可以从完全一致到部分命中渐进评估 Agent 的工具使用能力。在adk eval的tool_trajectory_avg_score中多个用例的轨迹匹配得分会取平均作为该评估集的整体工具行为质量分。5.2 结合 eval_config.json 的响应质量评分除了轨迹与文本匹配模板还提供了基于 rubric 的 LLM 判分器。仓库中的 eval_config.json 示例定义了一个rubric_based_final_response_quality_v1标准{ 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低于阈值视为该用例响应质量不达标judgeModelOptions.judgeModel作为裁判的模型示例中使用gemini-3-flash-preview与该模板 Agent 使用的模型一致judgeModelOptions.numSamples采样次数示例为 1rubrics评分细则数组每条含rubricId如relevance、helpfulness与rubricContent.textProperty对判分标准的自然语言描述该配置的意义在于response_match_score只是文本层面的相似度而 rubric 判分器能从是否直接回答用户问题是否提供有用信息等语义维度对最终回复做质量把关。由于配置采用 JSON 形式你可以自由扩展 rubric如增加safety、conciseness或更换判分模型与阈值。六、创建自定义 Evalset 的完整步骤依据模板 README 的指引结合仓库实际推荐按以下流程创建自己的评估集第 1 步复制模板。以 basic.evalset.json 为起点复制一份命名为custom.evalset.json或按能力域命名如weather_tools.evalset.json放在tests/eval/evalsets/目录下。第 2 步按 DESIGN_SPEC.md 的场景添加用例。逐条梳理设计文档中定义的 Agent 能力把每个能力对应为一个或多个 eval case。例如本模板的 Agent 具备天气与时间查询能力就应为get_weather、get_current_time各设计用例。第 3 步为能力测试声明期望的工具调用。对于需要工具参与的用例务必在conversation[].intermediate_data.tool_uses中写明期望的工具名与参数。参照本模板 Agentapp/agent.py的工具签名一个询问旧金山天气的用例可以写成{ eval_id: weather_sf, conversation: [ { user_content: { parts: [{text: Whats the weather in San Francisco?}] }, intermediate_data: { tool_uses: [ {name: get_weather, args: {query: San Francisco}} ] } } ], session_input: { app_name: app, user_id: eval_user, state: {} } }注意tool_uses中的args应与工具定义如get_weather(query: str)的参数名严格一致否则轨迹匹配会因参数不匹配而失分。第 4 步运行验证。执行make eval EVALSETtests/eval/evalsets/custom.evalset.json在生成的项目根目录下路径相对于项目根在仓库内对应agent_starter_pack/agents/adk_a2a/tests/eval/evalsets/custom.evalset.json观察tool_trajectory_avg_score与response_match_score迭代调整用例或 Agent 提示词直至达标。七、编写 Evalset 的最佳实践 Tips原文档给出的实践建议结合源码可进一步落地为可执行的检查清单起步用 3~5 个有代表性的用例覆盖每个核心能力至少一条路径。模板默认仅提供 2 个纯对话用例实际项目应在此基础上补齐工具类用例同时包含 happy path 与 edge casehappy path 验证工具被正确调用edge case 验证 Agent 在异常输入下不崩溃、不误用工具。例如对get_weather传入未知城市、对request_user_input触发追问场景为 DESIGN_SPEC.md 中的每个核心能力都建用例能力即验收标准评估集本质上是把设计文档中的能力描述翻译成可执行的机器检查在生产中发现 bug 时补充用例这是一个回归防线策略——线上暴露的问题先转化为新的 eval case再修复 Agent确保同类问题不再复发。此外从 Makefile 的实现可以看出eval-all会遍历目录下全部.evalset.json因此建议按能力域拆分文件避免单个 evalset 无限膨胀同时保持eval_config.json的 rubric 与团队质量口径一致让不同评估集之间的分数具有可比性。八、与其它质量手段的协同evalset 不是孤立的。在 adk_a2a 模板中它和以下机制共同构成质量保障体系集成测试tests/integration/test_agent.py 通过Runner与InMemorySessionService验证 Agent 能否正常产出流式文本响应属于能跑层面的冒烟验证而 evalset 验证跑得对层面的行为正确性A2A 协议验证模板通过make inspector启动 A2A Protocol Inspector 校验 Agent 的协议实现详见 adk_a2a 模板 README保证跨框架互操作性可观测性生成的项目可接入 BigQuery Agent Analytics 插件app/agent.py用于生产环境的运行监控——这与评估集形成开发期验证 生产期观测的闭环评估集在开发阶段发现问题可观测性在生产中暴露新问题而新问题又能沉淀为新的 eval case 回到开发期。九、小结Evalset 是 agent-starter-pack 内置的 Agent 行为验收机制核心要点可以概括为格式即约定.evalset.json用eval_cases conversation intermediate_data.tool_uses session_input四层结构把期望的 Agent 行为写成机器可读的标准命令即门禁make eval单评估集、make eval-all全量回归、EVALSET参数覆盖让评估轻松嵌入日常开发指标即反馈tool_trajectory_avg_score管工具调用是否准确有序response_match_score管响应是否达到预期配合 eval_config.json 的 rubric 判分器从语义层面把关响应质量迭代即增长从 3~5 个代表性用例起步随能力演进和线上问题持续补充用例让评估集成为 Agent 能力演进的行为回归测试集。按照本文的格式说明与步骤你可以在几分钟内为任何 ADK Agent 建立起第一套可运行的评估基线并把它接入make eval的日常循环。【免费下载链接】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），仅供参考