
agents-cli 评估数据集迁移指南从 ADK EvalSet 到 Agent Platform EvaluationDataset【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本指南面向在agents-cli新评估体系eval generate/eval grade/eval dataset synthesize/eval compare/eval analyze/eval metric list/eval optimize重构之前就开始使用该工具、项目里还残留着tests/eval/evalsets/旧格式评估文件的开发者。你将掌握旧*.evalset.json与新版*-dataset.json之间的完整 schema 差异、agents-cli scaffold upgrade的自动迁移行为以及单轮 / 多轮用例的手动转换方法最终能独立完成评估数据的平滑升级并正确验证。一、背景为什么评估数据格式变了agents-cli的评估能力最初构建在 ADK 的EvalSetschema 之上评估文件存放在项目的tests/eval/evalsets/目录下形如basic.evalset.json。评估体系重构之后所有评估命令eval generate、eval grade、eval dataset synthesize、eval compare、eval analyze、eval metric list、eval optimize都建立在Gemini Enterprise Agent Platform GenAI Eval SDK的EvaluationDataset/EvalCase类型之上评估数据源统一改为tests/eval/datasets/目录下的*-dataset.json文件。这一变更的核心动机是消除数据形状之间的桥接成本直接采用平台自身的 schema 后agents-cli无需再维护两套数据结构之间的映射即可解锁 Agent Platform 更完整的评估能力集——内置与自定义指标、LLM-as-judge 评分、数据集合成、回归对比、失败模式分析与提示词优化。需要特别说明的是如果你的项目里根本没有tests/eval/evalsets/目录就不需要做任何迁移操作。该判断逻辑同样体现在源码中——migrate_legacy_evalsets()在旧目录不存在时会直接返回no-op不会对项目产生任何副作用见 upgrade.py。二、变化总览新旧格式在目录、文件名、默认文件与 schema 来源四个维度上的对应关系如下维度旧格式ADKEvalSet新格式Agent PlatformEvaluationDataset目录tests/eval/evalsets/tests/eval/datasets/文件名*.evalset.json*-dataset.json默认文件basic.evalset.jsonbasic-dataset.jsonSchema 来源google.adk.evaluationagentplatform._genai.types.EvaluationDatasetagents-cli eval generate默认查找tests/eval/datasets/basic-dataset.json该默认值定义于 _paths.pyDEFAULT_INPUT_DATASET tests/eval/datasets/basic-dataset.json如果数据集文件用了其他名字需要通过--dataset PATH显式指定。从源码看eval generate对数据集的定位遵循命令行参数优先、默认文件兜底的策略resolve_input_dataset()在--dataset未提供时回退到{项目根目录}/tests/eval/datasets/basic-dataset.json若该文件也不存在则返回None命令随即报错提示指定--dataset PATH见 _paths.py 与 cmd_generate.py。三、Schema 变化详解3.1 两种合法的输入形态Shape A / Shape B新版格式的每条评估用例必须提供两种形态之一Shape A — 单提示词用例顶层提供prompt字段单条用户消息。适用于一次性用户查询的场景。Shape B — 连续对话用例N1 模式提供agent_data块其 turns 以一条用户消息结尾。agents-cli eval generate会在此之后追加下一条 agent 响应。旧EvalSetschema 中的单轮用例映射为 Shape A多轮用例映射为 Shape B——记录的历史轮次变为agent_data.turns并以你希望 agent 回应的那条用户消息收尾。该两种合法输入的约束在命令层同样有硬校验eval generate会逐条检查每个 eval case缺失prompt与agent_data两者时会直接抛出ClickException见 cmd_generate.py。3.2 外层信封Envelope新版最外层结构大幅简化eval_set_id、name、description三个顶层字段全部移除仅保留eval_cases。旧格式{ eval_set_id: basic_eval, name: Basic Agent Evaluation, description: Sample evaluation set for testing core agent functionality., eval_cases: [ ... ] }新格式{ eval_cases: [ ... ] }这一简化与自动迁移的实现一一对应_convert_eval_set()只保留eval_cases列表逐个用例经_convert_eval_case()转换后放入新信封见 upgrade.py。3.3 单轮用例Shape A单轮用例有四处关键变化eval_id→eval_case_id。首个 turn 的conversation[0].user_content上提为顶层prompt。session_input被移除——agent 状态初始化改由 agent 代码app/agent.py负责不再声明在评估数据里。新增role: user——这是 Agent PlatformContent类型的必填字段。旧格式{ 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_case_id: greeting, prompt: { role: user, parts: [{text: Hello, what can you help me with?}] } }从自动迁移源码可以确认这些字段级映射_convert_eval_case()先取eval_id旧字段或eval_case_id作为新用例 ID当对话仅有一轮时把user_content.parts直接装入{role: user, parts: [...]}的顶层prompt见 upgrade.py。3.4 多轮用例Shape B旧 schema 中多轮对话是conversation下的 turn 列表新 schema 中它们映射为 Shape B历史轮次放在agent_data.turns下历史中的最后一条用户消息就是eval generate将要回应的内容不设独立的顶层prompt。agent_data.turns[].events中的每条 event 包含author取值为user或agent_data.agents中声明的某个 agent ID与content用户 turn 的role为useragent turn 的role为model。旧格式两轮对话{ eval_id: follow_up, conversation: [ { user_content: { parts: [{text: Book a flight to Paris.}] }, final_response: { parts: [{text: What dates are you flying?}] } }, { user_content: { parts: [{text: Next Monday, returning Friday.}] } } ] }新格式Shape B{ eval_case_id: follow_up, agent_data: { agents: { flight_booker: { agent_id: flight_booker, agent_type: llm_agent, description: Books flights and answers itinerary questions., instruction: Help the user book flights. Ask clarifying questions about dates, origin, and passenger count before calling any booking tool., tools: [ { function_declarations: [ {name: search_flights, description: Search available flights.}, {name: book_flight, description: Book a flight by ID.} ] } ], sub_agents: [] } }, turns: [ { turn_index: 0, events: [ { author: user, content: { role: user, parts: [{text: Book a flight to Paris.}] } }, { author: flight_booker, content: { role: model, parts: [{text: What dates are you flying?}] } }, { author: user, content: { role: user, parts: [{text: Next Monday, returning Friday.}] } } ] } ] } }关于agent_data.agentsagentsmap 声明了被测 agent 系统的拓扑结构以 agent ID 为键每个条目携带该 agent 的配置——agent_type、description、instruction、toolsagent 可调用的 function declarations形状与google.genai.types.Tool一致以及sub_agents。每条 event 的author要么是user要么是这张 map 中存在的 agent ID——这正是多 agent 系统在评分阶段把响应与工具调用归因到正确子 agent 的方式。tools块允许评分器检查 agent 是否选对了工具且参数合理因此只要你的 agent 有可调用工具就应当包含它。对于单 agent 项目声明一个条目即可如上例所示对于多 agent 系统则列出每个 agent 并用sub_agents表达拓扑关系。示例中的取值仅作演示请按你的实际项目调整。转换完成后eval generate会针对这段历史运行 agent并把其回复作为下一条 agent event 追加进去生成一份可供eval grade使用的完整 trace。final_response与reference的区分一个容易混淆的点如果旧用例在被评分的最后一轮上设置了final_response来表达标准答案那是一个不同的概念——应放在顶层的reference字段中而不是混入agent_data.turns。历史中的真实响应进 turn history最后一条用户消息的目标答案进reference。自动迁移的实现正是这样处理的对于单轮用例turn 上的final_response会被转换为顶层reference对于多轮用例只有最后一轮i last_idx的final_response才写入reference中间轮次的final_response则作为 agent 事件author: agent、role: model插入事件流见 upgrade.py。四、自动迁移agents-cli scaffold upgradeagents-cli scaffold upgrade会检测遗留的*.evalset.json文件并自动转换为新格式。转换遵循以下规则新文件写入tests/eval/datasets/跳过已存在的目标文件不会覆盖保留旧目录方便你在删除前先核对转换结果eval generate会在下次运行时从你的在线 agent 填充agent_data.agents因此迁移器不会写入 stub。该逻辑在 upgrade.py 中完整实现migrate_legacy_evalsets()遍历tests/eval/evalsets/*.evalset.json目标文件已存在则记入 skipped 并跳过JSON 解析失败则记入 failed 并继续处理其余文件全部成功后提示All legacy evalsets migrated. You can delete tests/eval/evalsets/ once youve verified the converted files.。文件名转换规则为_legacy_to_new_filename()去掉.evalset.json后缀再追加-dataset.json见 upgrade.py。升级命令还支持--dry-run预演模式只报告会迁移多少个文件而不实际写入见 upgrade.py此外还会检查遗留的tests/eval/eval_config.json——由于新旧评分配置 schema 不同该文件不会自动转换只会输出警告提醒你参照迁移指南手动处理见 upgrade.py。值得注意的还有升级时的三方比较保护当某个tests/eval/datasets/*-dataset.json既存在于你的项目又存在于新模板、但旧模板中没有旧模板随附的是evalsets/而非datasets/时upgrade 会判定这是migrate_legacy_evalsets生成的你的内容按preserve保留处理而非视为与默认模板的冲突见 upgrade.py。这意味着自动迁移产出的文件不会被后续升级误覆盖。五、手动逐步转换如果你更愿意手工完成转换以单个文件tests/eval/evalsets/basic.evalset.json为例建新目录mkdir -p tests/eval/datasets复制文件cp tests/eval/evalsets/basic.evalset.json tests/eval/datasets/basic-dataset.json编辑新文件打开tests/eval/datasets/basic-dataset.json删除顶层字段删掉顶层的eval_set_id、name、description逐条转换eval_cases把每条用例的eval_id改名为eval_case_id然后按形态选择单轮Shape A把唯一 turn 的user_content上提为顶层prompt并补上role: user删除conversation数组与session_input块。多轮Shape B在agent_data.agents中声明 agent 拓扑agent ID 到其AgentConfig的映射再构建agent_data.turns[0].events列表其最后一条必须是希望 agent 回应的用户消息。将每个历史 turn 的user_content转为author: userrole: user的 event把记录到的 agent 响应转为author为对应 agent IDrole: model的 event。删除conversation数组与session_input块Shape B 不要设置顶层prompt。保存并验证运行agents-cli eval generate它应能自动发现该文件。全部转换无误后再删除旧目录tests/eval/evalsets/。多文件批量处理对每个*.evalset.json重复上述步骤。tests/eval/datasets/下的文件名应遵循*-dataset.json约定例如flight_booking.evalset.json变为flight_booking-dataset.json这与自动迁移器的命名规则完全一致。六、验证迁移结果agents-cli eval generate如果你沿用了默认文件名basic-dataset.jsoneval generate会自动拾取它。其他文件名则需要显式指定agents-cli eval generate --dataset tests/eval/datasets/your-file-dataset.json运行成功后会产出一份填充完成的 trace 文件默认位于artifacts/traces/traces_时间戳.json见 _paths.py可直接交给agents-cli eval grade进行评分。从命令实现看eval generate会先在本地启动 HTTP server 运行 agent项目存在fast_api_app.py时优先使用否则回退到adk api_server也可通过--url指向已运行或已部署的 agent见 cmd_generate.py。因此验证迁移时确保 agent 应用可正常加载、数据集 JSON 合法解析失败会明确报错Dataset file is not valid JSON且每个 case 都满足 Shape A 或 Shape B 的校验即可。七、迁移要点速查检查项说明目录tests/eval/evalsets/→tests/eval/datasets/文件名*.evalset.json→*-dataset.json顶层信封删除eval_set_id/name/description仅留eval_cases用例 IDeval_id→eval_case_id单轮用例conversation[0].user_content上提为顶层prompt补role: user删session_input多轮用例拓扑进agent_data.agents历史进agent_data.turns[0].events末条为用户消息不设顶层prompt标准答案旧final_response被评分的那一轮→ 顶层reference不进 turn history自动迁移agents-cli scaffold upgrade自动完成跳过已存在目标、保留旧目录、不写 stub支持--dry-run验证agents-cli eval generate默认文件自动识别其他文件用--dataset收尾验证通过后删除旧目录tests/eval/evalsets/完成上述转换后你的评估数据便与新评估体系完全对齐可以无缝使用平台侧的指标、评分、合成、对比与优化能力而不必再维护两套数据形状之间的桥接。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考