agents-cli 用户模拟评测实战：用 eval dataset synthesize 驱动 ADK Agent 的动态多轮评测

agents-cli 用户模拟评测实战用 eval dataset synthesize 驱动 ADK Agent 的动态多轮评测【免费下载链接】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本文介绍 Google agents-cli 评测体系中的用户模拟User Simulation机制当固定 prompt 无法覆盖 agent 的多种提问顺序与临场反应时agents-cli eval dataset synthesize会调用 Vertex AI 评测服务从 agent 的工具与指令中生成用户场景user scenario再由 LLM 驱动的用户模拟器逐场景扮演用户完成多轮对话产出的 trace 可跳过eval generate直接进入eval grade评分。读完后你将掌握该命令的全部 CLI 参数、输出文件结构、兼容指标的配置方式以及其底层执行链路与适用限制。框架限制ADK 项目。agents-cli eval dataset synthesize通过 ADK 加载并运行 agent因此仅适用于 ADK 项目其余评测环节eval generate、eval grade、指标体系、数据集 schema是框架无关的。何时使用用户模拟固定的评测 prompt 在多轮 agent 上往往不够用agent 可能以不同顺序向用户索要信息也可能以未预期的方式应答。逐条手工录制每个 user/agent 轮次既低效又脆弱。用户模拟的思路是让agents-cli eval dataset synthesize请求 Vertex AI 评测服务为你的 agent 生成用户场景然后由一个 LLM 支撑的用户模拟器逐一扮演用户与 agent 对话最终得到带完整agent_data.turns的 trace直接投入agents-cli eval grade。一个**用户场景user scenario**由两部分组成starting_prompt— 模拟用户的开场白conversation_plan— 自由文本描述规定模拟用户在后续对话中应如何行为。在 agents-cli 流程中这些场景不需要你自己编写——eval dataset synthesize会根据 agent 的工具描述与指令自动生成。确定性的手工评测用例例如回归覆盖请改用已录轮次格式直接在数据集中写agent_data.turns再用agents-cli eval generate回放。参见 dataset_schema.md。注意agents-cli eval generate要求每个 case 具有顶层prompt或agent_data它不会回放手工编写的user_scenariocase。运行eval dataset synthesize# 生成 3 个场景默认值模拟执行trace 写入 artifacts/traces/traces_ts.json agents-cli eval dataset synthesize # 用 instruction 与环境上下文引导场景生成 agents-cli eval dataset synthesize \ -n 5 \ --max-turns 8 \ --instruction Customer asking about refunds \ --environment-context E-commerce support; orders are visible by order_id # 为场景生成指定自定义模型默认服务端默认模型 agents-cli eval dataset synthesize --model gemini-2.5-proagents-cli eval dataset synthesize暴露的 CLI 参数参数作用-n / --count生成的场景数量默认 3最小 1--instruction引导场景生成的自然语言指令--environment-context模拟器可以依赖的世界背景例如可用数据--model用于场景生成的模型服务端调用不是模拟用户所用的模型--max-turns每个场景 user↔agent 轮次上限默认 5最小 1-o / --output输出路径默认artifacts/traces/traces_ts.json这些默认值在 CLI 源码中得到印证cmd_dataset.py 中--count与--max-turns均声明为click.IntRange(min1)默认分别为 3 和 5。运行前提与环境变量行为synthesize在本地运行你的 agent并从 agent 的.env读取配置读取整个文件——GOOGLE_GENAI_USE_VERTEXAI、GEMINI_API_KEY、GOOGLE_CLOUD_*以及应用自定义变量没有--project/--region参数。在 Vertex AI 上GOOGLE_CLOUD_LOCATION还会决定服务端场景生成调用的端点而该调用只支持部分评测区域——除非确认所在区域受支持否则保持globalscaffold 默认值不变。从源码结构看命令的执行流程是cmd_dataset.py通过pyproject.toml定位项目根并读取agents-cli-manifest.yaml中的agent_directory确定 agent 目录执行uv sync --dev --extra eval同步评测依赖将内置 runner 脚本暂存到项目下的.agents-cli-scripts/目录并以uv run python在用户项目的虚拟环境中执行脚本每次运行覆盖、结束后清理整体超时 600 秒超时错误会提示检查.env中的GOOGLE_CLOUD_LOCATION参数以 JSON 传入 runnercount、generation_instruction来自--instruction、environment_context、model_name来自--model。模拟器内部不可从 agents-cli 配置。扮演用户一方的 LLM 模拟器运行在 _synthesize_runner.py 内使用硬编码的 ADK 默认值用户声音模型为gemini-2.5-flash、默认 thinking 配置、无custom_instructions。只有--max-turns会传递到模拟器作为LlmBackedUserSimulatorConfig.max_allowed_invocations。不存在eval_config.yaml配置项、不存在--simulator-model参数也无法在不直接编辑_synthesize_runner.py的情况下覆盖custom_instructions或model_configuration。synthesize写出什么输出是一个 JSONEvaluationDataset文件位于-o指定路径。每个 case 包含eval_case_id— 服务端生成的 UUIDuser_scenario— 生成的{starting_prompt, conversation_plan}为可追溯性而保留agent_data.turns— 完整模拟对话用户事件、agent 应答、工具调用、工具响应。由于agent_data.turns已完整填充该文件本身就是可直接评分graded-ready的 trace。跳过eval generate直接执行eval gradeagents-cli eval dataset synthesize agents-cli eval grade # 默认读取 artifacts/traces/这一路径约定在 _paths.py 中有单一定义stage-2 产物已填充的 trace位于artifacts/traces/traces_ts.json由eval generate或eval dataset synthesize产生、供eval grade消费--output若以/结尾或指向已有目录则在其内部写入带时间戳的文件resolve_output_path。部分场景失败不阻塞流程。如果某些场景模拟失败这些 case 会以空的agent_data.turns留在输出文件中并在 stderr 打印告警其余成功 case 照常进入eval grade。对应实现在 runner 的模拟循环每个场景的异常被单独捕获、invocations置空并计入failures最终统一输出x/N scenarios failed during simulation; their agent_data will have empty turns.告警。从 runner 源码还可确认 trace 的组装细节_synthesize_runner.py每次 ADKInvocation被转换为一个 turn带turn_index、turn_id与events列表事件序列依次为user_contentauthoruser、中间调用事件/工具调用来自invocation_events或tool_uses、以及final_responseauthoragent同时通过_final_response_from_invocations从最后一个含文本的应答中抽取responses[0]保证LLMMetric与custom_function能读到instance.response而不报错。兼容的评分指标合成 trace 是多轮对话且没有标准答案ground truth因此只有三个多轮指标可用其他内置指标在多轮 trace 上会返回 400基于参考的指标也没有可匹配的参考内容指标为什么适用multi_turn_task_success自适应 rubric 判定模拟用户的目标是否达成multi_turn_trajectory_quality自适应 rubric 评估跨轮次的 agent 推理multi_turn_tool_use_quality自适应 rubric 评估跨轮次的工具调用与 metrics-guide.md 中的指标参考一致这三个指标在 Trace 列均标注为any而multi_turn_general_quality、multi_turn_text_quality需要eval generate不产生的conversation_history字段在 agent trace 上同样 400。针对合成 trace 的tests/eval/eval_config.yaml示例metrics_to_run: - multi_turn_task_success - multi_turn_trajectory_quality - multi_turn_tool_use_quality执行agents-cli eval grade --config tests/eval/eval_config.yamleval_config.yaml会被eval run、eval grade、eval submit读取eval dataset synthesize则忽略它。实现链路从 CLI 参数到 Vertex AI 调用把文档描述与 runner 源码 对照可以还原完整调用链加载 agent通过 ADK 的AgentLoader从agent_directory加载 agent并先_load_agent_dotenv把项目.env全量注入os.environ已有 OS 环境变量优先overrideFalse与 ADK 的load_dotenv_for_agent行为一致构建 AgentInfotypes.evals.AgentInfo.load_from_agent(agentagent)从 agent 提取指令与工具声明——这正是场景质量完全取决于 agent 元数据的出处。runner 内还有_safe_tool_declarations兜底对无tools属性的 workflow agent如SequentialAgent返回空声明而非崩溃对不可内省的 ADK toolset如 MCP toolset跳过被跳过的 toolset 仍保留在真实 agent 上其工具调用照常出现在 trace 中服务端场景生成调用client.evals.generate_conversation_scenarios(agent_info..., config..., allow_cross_region_modelTrue)project/location取自.env的GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION。CLI 侧传入的count、generation_instruction、environment_context、model_name都进入config本地用户模拟对每个 case 构建ConversationScenario(starting_prompt, conversation_plan)与LlmBackedUserSimulator仅max_allowed_invocationsmax_turns一项配置由EvaluationGenerator._generate_inferences_from_root_agent驱动真实 agent 与模拟器对话初始会话为app_nameuser_simulation_app、user_iduser_simulation_default_user并传入 agent 的reset_data作为会话间重置钩子落盘所有 case 组成EvaluationDataset以model_dump_json(indent2, exclude_noneTrue)写到输出路径。配套测试也可以佐证 trace 契约的稳定性test_eval_generate.py 中TestGradeContract明确turn 必须带turn_index/turn_id、输出必须能被eval grade使用的EvaluationDataset模型解析防止 trace 形状与服务端约定漂移。实用注意事项场景质量完全取决于 agent 元数据。generate_conversation_scenarios读取 agent 的指令与工具描述来生成可信的用户行为。含糊的工具描述只会得到含糊的场景——在新 agent 上首次运行 synthesize 之前先把工具 docstring 写精确。--max-turns是硬上限。模拟用户可能提前停止目标达成或放弃--max-turns只是防止对话失控的保险丝不是期望轮次。重跑 synthesize 会生成全新场景。没有 seed 参数——每次调用都产生新的场景集合。需要可重复的回归覆盖时直接手写agent_data.turns见 dataset_schema.md而不是依赖synthesize。实验性命令。CLI 在每次执行时都会打印 eval dataset synthesizeis experimental and may change 警告行为与参数可能调整agents-cli eval dataset synthesize --help输出的参数列表才是当前版本的权威来源。小结用户模拟是 agents-cli 评测飞轮中准备数据阶段的关键加速器没有现成对话数据时eval dataset synthesize从 agent 自身元数据合成多轮场景并本地跑通模拟器输出带完整agent_data.turns与保留user_scenario的 trace 文件直接对接eval grade与三个多轮自适应 rubric 指标。使用时的核心约束有三条仅支持 ADK 项目、模拟器内部参数不可配置只能调--max-turns、场景不可复现无 seed——确定性回归应始终落到手写agent_data.turns上。更完整的命令与指标说明见 SKILL.md、metrics-guide.md 与原文档 user-simulation.md。【免费下载链接】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），仅供参考