在实际的 LLM Agent 工程落地中评测场景的供给速度往往落后于工具数量的增长速度。Agent Seer 这一类思路的核心是把工具规格Tool Specification当作评测场景的原料通过解析 OpenAPI、JSON Schema 或函数签名程序自动合成 Agent 评测场景从而减少人工编写场景的成本。这篇文章从工具规格理解的角度出发拆解合成评测场景的原理、最小实现、验证方式和排查路径帮助你把这个思路落到自己的 Agent 评测体系里。读完这篇文章你能掌握一套可复现的“规格读取 - 场景合成 - 可执行校验 - 指标评估”闭环流程并且知道在真实项目中哪些环节最容易出问题。文章里给出的代码是可直接运行的最小示例但落地到业务系统时需要结合你自己的工具注册中心、评测平台和模型版本做适配。1. 先理解 Agent 评测场景为什么比测试用例更难写1.1 评测场景的三个组成要素一个 Agent 评测场景本质上是一道“有标准答案的开放题”。它和传统接口测试用例很像但多了一层规划与决策的复杂度。一个完整的 Agent 评测场景通常由三部分组成用户任务一段自然语言描述例如“帮我查一下今天上海到北京的航班选最早那班”。期望轨迹Agent 应当调用的工具集合、调用顺序和关键参数例如先调用flight.search再调用flight.select。成功判定最终结果是否满足用户任务可以是最终答案比对也可以是任务完成标志位。这三部分缺一不可。只有用户任务没有期望轨迹评测时只能靠人工看日志只有工具调用没有任务目标评测就会退化成“工具调用是否合法”无法反映 Agent 的真实使用体验。1.2 人工编写评测场景的三个瓶颈靠人工写 Agent 评测场景最常见的问题是数量不够、覆盖不匀、更新太慢。数量不够好理解。一个系统接入 50 个工具每个工具至少要有正常调用、缺参、参数非法、权限不足、返回错误这 5 类场景这就是 250 个基础场景。如果再考虑多工具组合场景数量会很快膨胀到几千甚至上万。人工写到哪里算哪里很难有穷尽感。覆盖不匀也很典型。写评测的人通常会重点覆盖自己熟悉的工具冷门工具的失败分支几乎没有人管。等到 Agent 在生产环境真的调用冷门工具时才发现评测场景里根本没有覆盖错误的交互方式。更新太慢出现在工具规格变化时。接口新增了参数、必填项改成了选填、某个工具有了新错误码这些都是评测场景必须同步变化的点。如果场景是人工维护的规格变更后基本不可能在当天完成全量更新。1.3 工具规格为什么能成为评测场景的原料工具规格是服务提供方对“这个工具能干什么、需要什么输入、会返回什么”的形式化描述。OpenAPI 的 path、operationId、parameters、requestBodyJSON Schema 的 type、required、enum、formatPython 函数签名里的类型注解和 docstring都属于工具规格的一部分。这些信息天然具备评测价值。因为工具规格定义了工具调用的合法边界而评测场景恰恰需要围绕合法边界去制造“合法调用”和“非法调用”两类输入。只要程序能读懂规格就能自动推导出一个工具可能遇到的所有参数情况和错误分支。Agent Seer 这个命名强调的正是这种“先理解、再预见”的思路系统像观察者一样先读工具规格再预测 Agent 在实际使用中会遇到哪些情况并把预测结果组织成可执行的评测场景。2. 工具规格里到底藏着哪些可评测信息把工具规格当作评测原料之前要先清楚一个事实工具规格不是只有参数列表。真正有价值的评测信息藏在接口契约、行为约束、错误语义和工具间依赖关系四个层面。2.1 接口契约参数、类型与必填关系最直接的评测信息来自参数定义。一个参数是否必填、是什么类型、有没有枚举值、有没有默认值这些字段直接决定了评测场景的边界。必填参数用于生成“缺参场景”。程序遍历所有必填参数分别构造“缺少该参数、其他参数正常”的输入就能得到一组完整的缺参评测用例。类型字段用于生成“错型场景”。integer 参数可以尝试传字符串string 参数可以尝试传对象boolean 参数可以尝试传数字。这些错误输入是评测 Agent 是否能前置校验参数、是否能给出友好提示的关键。枚举值则用于生成“合法值采样”和“非法值越界”两类场景。有 enum 的字段合法值从 enum 中取非法值取一个不在 enum 中的同类型值即可。下表总结了接口契约信息和评测场景的对应关系规格字段可评测内容合成方向required缺参时 Agent 是否主动澄清或报错缺参场景type参数类型校验是否前置错型场景enum枚举值边界是否被遵守越界枚举场景format日期、邮箱、URL 等格式约束格式非法场景default缺省值行为是否符合预期默认值回退场景2.2 行为约束副作用、状态变化与调用顺序参数只是规格的表面。真正决定评测难度的是工具的行为约束也就是“调用这个工具会改变什么状态”。例如order.cancel这个工具它的行为约束是订单状态只能从“已支付”变为“已取消”且一个订单只能取消一次。评测场景因此要覆盖重复取消、取消已发货订单、取消已取消订单这些状态机分支。这类信息在规格描述里通常是以文字形式存在的例如“该接口只允许取消待发货订单”“同一个订单号只能调用一次”。自动解析这类约束的难度较高常见做法是先用规则提取关键词再人工确认约束语义。在最小实现阶段可以先把这类约束手工标注在工具规格的扩展字段中后续再引入大模型辅助抽取。多工具链的调用顺序也属于行为约束。一个典型的电商助手评测场景是“查询订单 - 判断是否可取消 - 执行取消 - 确认取消结果”。规格中order.cancel的输入参数order_id来源于order.list的返回值这种输入输出之间的关联关系就是合成多步场景的依据。2.3 错误语义失败分支是评测的富矿很多评测场景集中覆盖成功路径但 Agent 在生产环境最容易出问题的恰恰是失败分支。工具规格中的错误码、错误信息和异常响应结构是合成失败场景最直接的原料。OpenAPI 的 responses 定义里通常能看到 400、401、403、404、500 等状态码。每个状态码背后对应的都是 Agent 必须处理的局面400参数语义错误Agent 应该修正参数后重试而不是原样复述错误。401/403权限不足Agent 应该明确告诉用户没有权限或引导用户走授权流程。404资源不存在Agent 应该判断是否换一个查询条件。500/502/503服务不可用Agent 应该提示稍后重试而不是无限重试同一个请求。合成错误场景时可以针对每个工具的错误码生成一条用户任务并在期望轨迹中显式声明“该场景预期 Agent 不继续调用该工具而是输出错误说明”。2.4 四种工具规格来源与评测信息量对比不同工具规格的承载形式不同能提取的评测信息量也不一样规格来源典型载体评测信息量适用场景开放接口文档OpenAPI / Swagger高含参数、错误码、请求响应结构REST 类工具函数定义Python 类型注解 docstring中参数类型和语义描述较完整本地工具数据库操作描述SQL 视图 / 表和字段说明中能推导出参数和约束数据查询类工具纯自然语言说明使用手册 / 提示词片段低需要额外抽取缺少结构化文档的存量工具如果你的工具规格是纯自然语言建议先做一步结构化转换把工具名、参数列表、错误码、状态约束整理成统一的 JSON 格式再进入评测场景合成阶段。否则后续每一步都会因为解析不稳定而出现问题。3. 最小实现用 Python 从 OpenAPI 规格合成评测场景下面进入可运行的部分。这个最小实现使用 Python 3.10不依赖第三方库也能跑通。目标是从一份 OpenAPI 规格中合成正常调用、缺参和错误处理三类基础评测场景并输出标准 JSON 场景集。3.1 准备环境与样例规格本地只需要 Python 环境和一份 OpenAPI 格式的规格文件。这里用一个简化版计算器工具的 OpenAPI 片段做演示文件保存为tool_spec.json{ openapi: 3.0.0, info: { title: Calculator Tools, version: 1.0.0 }, paths: { /add: { post: { operationId: calculator.add, summary: 计算两个整数相加, parameters: [ { name: a, in: query, required: true, schema: {type: integer} }, { name: b, in: query, required: true, schema: {type: integer} } ], responses: { 200: { description: 相加结果 }, 400: { description: 参数不是整数 } } } }, /divide: { post: { operationId: calculator.divide, summary: 计算两个整数相除, parameters: [ { name: a, in: query, required: true, schema: {type: integer} }, { name: b, in: query, required: true, schema: {type: integer} } ], responses: { 200: { description: 相除结果 }, 400: { description: 除数为零 } } } } } }这份规格虽然简单但已经包含了合成评测场景所需的全部基础元素工具名、参数名、参数类型、必填关系、错误码定义。3.2 定义评测场景的数据结构先用 dataclass 把工具规格和评测场景建模。这里的数据结构就是后续所有逻辑的公共语言。from dataclasses import dataclass, field from typing import Any, Dict, List, Optional dataclass class ParamSpec: name: str param_type: str required: bool False description: str enum: Optional[List[Any]] None default: Any None dataclass class ToolSpec: name: str description: str method: str path: str params: List[ParamSpec] field(default_factorylist) error_codes: List[str] field(default_factorylist) dataclass class Scenario: scenario_id: str tool_name: str difficulty: str user_task: str expected_calls: List[Dict[str, Any]] expected_behavior: str normal_callScenario.expected_calls里存放的是 Agent 应当产生的工具调用序列每个元素包含tool和args两个字段。expected_behavior字段用于标识该场景预期是正常调用、缺参澄清还是错误处理。3.3 解析工具规格下面是 OpenAPI 解析函数。它把paths下的每个接口变成一个ToolSpec对象重点提取参数和响应状态码import json def load_tool_specs(path: str) - List[ToolSpec]: with open(path, r, encodingutf-8) as f: spec json.load(f) tools [] for api_path, path_item in spec.get(paths, {}).items(): for method in (get, post, put, delete): op path_item.get(method) if not op: continue params [] for p in op.get(parameters, []): schema p.get(schema, {}) params.append(ParamSpec( namep[name], param_typeschema.get(type, string), requiredp.get(required, False), descriptionp.get(description, ), enumschema.get(enum), defaultschema.get(default), )) error_codes [ code for code in op.get(responses, {}).keys() if code not in (200, 201, 204) ] tools.append(ToolSpec( nameop.get(operationId, f{method}_{api_path}), descriptionop.get(summary) or op.get(description) or , methodmethod.upper(), pathapi_path, paramsparams, error_codeserror_codes, )) return tools这里要注意operationId是工具注册系统里最常用的唯一标识。如果你的 OpenAPI 规格没有写operationId建议先用“方法_路径”拼接后续再和工具注册中心对齐命名规范。3.4 合成三类基础场景场景合成最核心的逻辑是参数值生成。先定义一个根据参数类型生成样例值的函数def sample_value(param_type: str, enum: Optional[List[Any]] None) - Any: if enum: return enum[0] return { integer: 1, number: 1.0, string: test_value, boolean: True, array: [], object: {}, }.get(param_type, test_value)然后合成正常调用场景。正常场景要求所有必填参数都有值期望轨迹是一次完整工具调用def build_happy_path_scenario(tool: ToolSpec) - Scenario: args {} for p in tool.params: if p.required: args[p.name] sample_value(p.param_type, p.enum) return Scenario( scenario_idf{tool.name}_happy_path, tool_nametool.name, difficultyeasy, user_taskf请调用{tool.name}完成一次正常调用工具说明{tool.description}, expected_calls[{tool: tool.name, args: args}], expected_behaviornormal_call, )接下来合成缺参场景。它针对每个必填参数生成一个“故意缺失该参数”的用户任务预期 Agent 应该再次询问参数或提示参数缺失def build_missing_param_scenarios(tool: ToolSpec) - List[Scenario]: scenarios [] for p in tool.params: if not p.required: continue args {} for other in tool.params: if other.name ! p.name: args[other.name] sample_value(other.param_type, other.enum) scenarios.append(Scenario( scenario_idf{tool.name}_missing_{p.name}, tool_nametool.name, difficultyhard, user_taskf请调用{tool.name}但你没有获得参数 {p.name}需要先向用户确认, expected_calls[{tool: tool.name, args: args}], expected_behaviorask_for_missing_parameter, )) return scenarios最后合成错误处理场景。它针对工具规格中定义的每个错误码生成一条任务预期 Agent 不再发起同样请求而是输出可理解的错误提示def build_error_scenarios(tool: ToolSpec) - List[Scenario]: scenarios [] for code in tool.error_codes: scenarios.append(Scenario( scenario_idf{tool.name}_error_{code}, tool_nametool.name, difficultyhard, user_taskf调用{tool.name}时预期会返回 {code} 错误请观察 Agent 是否能合理处理失败结果, expected_calls[], expected_behaviorfhandle_error_{code}, )) return scenarios3.5 输出标准 JSON 场景集把上面三个生成函数组合起来并对生成后的场景做序列化输出def synthesize(tools: List[ToolSpec]) - List[Dict[str, Any]]: all_scenarios [] for tool in tools: all_scenarios.append(build_happy_path_scenario(tool)) all_scenarios.extend(build_missing_param_scenarios(tool)) all_scenarios.extend(build_error_scenarios(tool)) return [scenario_to_dict(s) for s in all_scenarios] def scenario_to_dict(s: Scenario) - Dict[str, Any]: return { scenario_id: s.scenario_id, tool_name: s.tool_name, difficulty: s.difficulty, user_task: s.user_task, expected_calls: s.expected_calls, expected_behavior: s.expected_behavior, } if __name__ __main__: specs load_tool_specs(tool_spec.json) scenarios synthesize(specs) with open(scenarios.json, w, encodingutf-8) as f: json.dump(scenarios, f, ensure_asciiFalse, indent2) print(fgenerated {len(scenarios)} scenarios)运行后scenarios.json里会同时包含calculator.add_happy_path、calculator.add_missing_a、calculator.add_missing_b、calculator.add_error_400这类场景。这个最小实现已经具备了一个评测场景生成器的骨架。4. 让合成场景具备可执行性和可判定性生成场景只是第一步。真正决定评测体系能不能用的是场景是否可执行、期望结果是否可判定。不能执行、不能判定的场景只会污染评测数据。4.1 用 Mock 工具服务验证场景可执行合成出来的场景要先在模拟环境里跑一遍确认它在评测平台中不会因为“工具不存在”“参数格式错误”这类低级问题直接失败。Mock 工具服务的作用是用固定逻辑模拟真实工具的行为让场景生成器可以先内测。def mock_execute(tool: ToolSpec, args: Dict[str, Any]) - Dict[str, Any]: missing [p.name for p in tool.params if p.required and p.name not in args] if missing: return { status: error, error_type: missing_parameter, missing: missing, } for p in tool.params: if p.name in args and args[p.name] is None: return { status: error, error_type: invalid_parameter, param: p.name, } return {status: ok, data: {echo: args}}校验逻辑可以简单到“所有场景都调用一次 mock_execute观察是否出现异常”。这个检查点不能替代真实评测但它能保证场景集里不会混入明显不可执行的条目。4.2 期望轨迹与成功判定设计期望轨迹的判定要区分“严格相等”和“语义匹配”。严格相等适合参数值由规格枚举值决定的场景语义匹配适合自然语言任务例如“最早那班航班”可能需要一个排序规则函数来判断。def judge(expected_calls, actual_calls): if not expected_calls: return {pass: True, reason: no_call_expected} if len(actual_calls) ! len(expected_calls): return {pass: False, reason: call_count_mismatch} for expected, actual in zip(expected_calls, actual_calls): if expected[tool] ! actual.get(tool): return {pass: False, reason: tool_mismatch} if expected[args] ! actual.get(args): return {pass: False, reason: args_mismatch} return {pass: True, reason: all_match}这个判定函数只适合最小示例。真实场景中Agent 可能先调用一个查询工具再根据结果调用第二个工具这种情况下期望轨迹会包含两个调用且第二个调用的参数依赖第一个调用的返回值不能用固定参数做严格比对。4.3 自动去重与质量过滤场景合成会产生大量重复内容。同一个工具缺两个参数和缺三个参数生成的用户任务可能看起来不同但评测语义完全一样。去重不能只看文本而要对“工具名 期望行为 参数约束”做组合指纹。def scenario_fingerprint(s: Dict[str, Any]) - str: return json.dumps({ tool: s[tool_name], behavior: s[expected_behavior], call_count: len(s[expected_calls]), }, sort_keysTrue) def deduplicate(scenarios: List[Dict[str, Any]]) - List[Dict[str, Any]]: seen set() result [] for s in scenarios: fp scenario_fingerprint(s) if fp not in seen: seen.add(fp) result.append(s) return result除了去重还要过滤掉质量不合格的场景。常见过滤规则包括用户任务为空、期望调用序列为空但预期行为不是错误处理、参数值全部来自同一样例值导致场景相似度过高、工具描述缺失导致用户任务无法独立理解。4.4 合成场景的四个质量检查点合成完成后建议按以下四个检查点人工抽审可读性用户任务是否像一个真实用户会提出的问题而不是“请调用 calculator.add 完成一次正常调用”这种机器味过重的表达。可执行性场景里的工具是否都在评测环境注册参数类型是否与规格一致。期望合理性期望调用序列是否会导致用户的最终任务被满足而不是只满足了一个中间步骤。错误分支有效性错误处理场景是否真的会触发错误还是 mock 工具根本不返回该错误码。如果抽审发现某类场景大量不可用说明合成逻辑需要调整。比如用户任务模板太机械应该增加模板池和自然语言改写层。5. 常见问题与排查路径把合成评测场景引入评测体系时下面四类问题出现频率最高。每类问题都按“现象 - 原因 - 检查方式 - 处理建议”的顺序给出排查路径。5.1 合成场景不贴合真实业务语义现象是场景生成了一大批但看起来都是机器的排列组合用户任务读起来不像真人会说的话评测指标也偏低。原因通常是合成模板只用了operationId和参数名没有结合工具描述中的业务语义。例如把“计算两个整数相加”写成了“请调用 calculator.add 完成一次正常调用”用户任务的自然度不够。检查方式是随机抽取 20 个合成场景人工判断“如果这是一个真实用户你是否会这样提问”。如果这类场景占比超过一半就要优化模板池。处理建议是建立多套用户任务模板把工具描述、参数含义、目标动作注入模板中再增加一组同义改写模板让同一个工具调用意图可以有不同的自然语言表达。5.2 场景不可执行或期望结果与规格矛盾现象是评测平台上运行合成场景时大量场景报“工具不存在”或“参数校验失败”但工具本身是正常的。原因通常是OpenAPI 规格和实际工具实现之间存在漂移。规格里写的是integer类型实际工具要求string规格里没有声明必填实际工具缺了该参数就报错。检查方式是先跑一遍 mock 校验流程确认场景在纯规格层面可执行再对比真实工具注册信息和 OpenAPI 规格的差异。可以写一个规格差异报告脚本把params、type、required、error_codes字段逐个 diff。处理建议是建立规格版本管理任何工具规格变更都触发场景重新合成并用“合成即执行”的校验流水线保证场景集和工具实现保持一致。5.3 场景重复度高、覆盖度不足现象是场景集很大但真正能发现 Agent 缺陷的场景很少。某些工具的失败分支被反复覆盖其他工具却只有正常调用场景。原因通常是去重逻辑只做了文本去重没有做语义去重生成逻辑对所有工具一视同仁没有根据工具复杂度分配场景数量。检查方式是统计每个工具的tool_name分布和expected_behavior分布。如果 80% 的场景集中在 20% 的工具上就要检查生成策略。处理建议是引入场景覆盖率报告按工具维度统计正常调用、缺参、错误处理、多工具链四类场景的数量占比缺哪类补哪类。同时对工具按参数数量、依赖关系、错误码数量打复杂度分复杂度高的工具生成更多场景。5.4 参数组合爆炸与生成耗时问题现象是工具参数一多场景数量指数级增长生成流程跑一次要很久评测集也大量冗余。原因通常是生成逻辑对所有参数组合做了笛卡尔积没有做组合裁剪。一个工具 10 个参数每个参数有 3 种取值全组合就是 59049 个场景。检查方式是打印每个工具的派生场景数量看是否存在明显的长尾。处理建议是采用 pairwise 组合策略保证任意两个参数的组合都被覆盖但不穷举全部组合。对于多工具链场景限制工具组合深度为 3 层以内并且在每一层只保留和上一层输出有参数依赖关系的工具。下表汇总了这几类问题的快速排查参照问题现象常见原因检查方式处理建议场景像模板拼凑缺少语义模板和自然语言改写人工抽读用户任务建设模板池和同义改写层场景跑不通规格与实现漂移mock 校验 规格 diff规格版本化 生成即执行重复多覆盖少只做文本去重统计工具与行为分布覆盖率报告 按复杂度分配生成耗时过高参数全组合爆炸统计派生场景数量pairwise 组合 限制链式深度6. 生产环境落地建议与扩展方向最小实现跑通后要把工具规格驱动的评测场景合成做成生产能力还需要补齐几个关键环节。6.1 从离线场景合成走向持续评测离线合成一批场景只是起点。生产环境要做的是把“规格变更”和“评测场景更新”绑定起来让工具注册中心在接口变更时自动触发场景合成任务随后自动运行评测并把结果写入回归报告。落地时建议区分三个环境环节学习/开发环境测试环境生产环境场景来源单个 OpenAPI 文件工具注册中心快照工具注册中心 人工增补校验方式手动抽查自动 mock 执行自动执行 人工抽审期望判定固定 golden answer规则 模型判分混合多维度判分场景集管理本地目录版本化存储版本化存储 CI 门禁6.2 规格版本管理与场景回归对照工具规格经常变化。如果规格变了场景没有重新生成评测结果就无法反映当前 Agent 的表现。生产环境必须给规格建立版本号每个版本对应一组生成时间、生成参数、场景数量和抽审结果。场景回归对照能做两件事一是当 Agent 模型升级时用同一份场景集对比新旧模型的指标变化二是当工具规格升级时检查哪些旧场景失效、哪些新场景需要补充。没有版本管理这两件事都做不了。建议至少保存以下元数据规格文件哈希、生成脚本版本、生成时间、工具数量、场景数量、抽审通过率、关联的 Agent 版本。6.3 结合真实调用日志反哺场景生成工具规格是静态原料真实调用日志是动态原料。生产环境积累的用户查询、Agent 调用序列、失败日志可以用来反哺场景生成逻辑。例如从日志中提取高频的用户任务模板用它替换模板池里的人工模板从失败日志中提取出现频率最高的错误码把它加入错误场景的合成优先级从真实工具调用链中提取常见调用顺序把它固化为多工具链场景模板。这一步是让评测场景从“规格能覆盖什么”走向“真实用户会问什么”的关键。规格决定了合法边界日志决定了真实分布两者结合才能生成既全面又贴近实际的高质量评测集。6.4 生产落地前检查清单在把工具规格驱动的场景合成上线之前建议逐项检查以下清单[ ] 工具规格是否有稳定的获取入口而不是散落在各处的手工文档。[ ] 规格变更是否能自动触发场景重新合成而不是依赖人工手动跑脚本。[ ] 合成场景是否有独立版本能和规格版本、Agent 版本对应起来。[ ] 是否已经建立“合成即执行”校验保证进入评测集的场景可运行。[ ] 场景集是否按工具、难度、期望行为三个维度产出覆盖率统计。[ ] 是否有人工抽审机制抽审比例建议不低于新增场景的 10%。[ ] 缺参、错型、错误处理、多工具链四类场景是否都有专门生成器。[ ] 期望判定是规则判分还是模型判分两类判分的边界是否明确。[ ] 规格变更后旧场景是否被标记为废弃避免继续计入回归指标。[ ] 评测失败时是否能快速定位是 Agent 模型问题、场景问题还是工具问题。这份清单可以作为评审会议上的自查表也可以作为新接入工具时评测团队的操作规范。工具规格驱动的评测场景合成核心价值不在于完全替代人工评测设计而在于把 AI Agent 评测的产能从“人肉编写”提升到“规格即评测”的自动化程度。真正难的不是生成场景而是让场景集始终保持与规格一致、与真实用户语义贴近、并且可以被机器稳定判定。从一份 OpenAPI 文件开始先跑通最小闭环再逐步接入工具注册中心、真实日志和版本化评测流水线这是目前最值得实践的一条路径。
