企业官网建设流程全解析

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 来源四个维度上的对应关系如下：

agents-cli eval generate默认查找tests/eval/datasets/basic-dataset.json，该默认值定义于 _paths.py（DEFAULT_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 — 连续对话用例（"N+1" 模式）：提供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）

单轮用例有四处关键变化：

1. eval_id→eval_case_id。
2. 首个 turn 的conversation[0].user_content上提为顶层prompt。
3. session_input被移除——agent 状态初始化改由 agent 代码（app/agent.py）负责，不再声明在评估数据里。
4. 新增"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为"user"，agent 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.agents

agentsmap 声明了被测 agent 系统的拓扑结构：以 agent ID 为键，每个条目携带该 agent 的配置——agent_type、description、instruction、tools（agent 可调用的 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 upgrade

agents-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 you've 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为例：

1. 建新目录：mkdir -p tests/eval/datasets
2. 复制文件：cp tests/eval/evalsets/basic.evalset.json tests/eval/datasets/basic-dataset.json
3. 编辑新文件：打开tests/eval/datasets/basic-dataset.json
4. 删除顶层字段：删掉顶层的eval_set_id、name、description
5. 逐条转换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: "user"（role: "user"）的 event，把记录到的 agent 响应转为author为对应 agent ID（role: "model"）的 event。删除conversation数组与session_input块；Shape B 不要设置顶层prompt。
6. 保存并验证：运行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.json），eval 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 的校验即可。

七、迁移要点速查

完成上述转换后，你的评估数据便与新评估体系完全对齐，可以无缝使用平台侧的指标、评分、合成、对比与优化能力，而不必再维护两套数据形状之间的桥接。

【免费下载链接】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