从工具规格到评测场景：Agent Seer让评测自动出题

Agent 类的应用跑了半年之后很多团队会碰到一个几乎无法回避的瓶颈模型换了一个又一个Prompt 调了一轮又一轮但评测集还是最初人工攒出来的那几十条。更尴尬的是当 Agent 接入了十几个工具之后你根本说不清楚这些工具的所有正确调用方式、边界输入和典型组合到底有没有被覆盖到。测试场景的产出速度远远跟不上工具迭代的速度。这篇文章要聊的 Agent Seer提出了一种非常值得关注的解题思路不是靠人力去写评测场景而是让系统去“读懂”工具规格再基于工具规格自动合成评测场景。换句话说过去我们是拿着题库考 Agent现在变成“考官”先读一遍工具说明书然后自己出题。这个方向本质上解决的是 Agent 评测成本结构中最高的一块——出题成本。读完这篇文章你会理解工具规格是什么、合成评测场景的核心流程怎么拆、工程上如何落地一个最小可运行的实现以及在实际项目中容易踩哪些坑。1. 为什么需要 Agent SeerAgent 评测里最贵的环节是“出题”很多团队对 Agent 评测的理解还停留在“准备一批用户问题跑一遍模型看回答对不对”。但在真实的 Agent 应用中这个思路有一个致命问题Agent 的行为空间不是“生成一段文字”而是“决定调用哪个工具、传什么参数、按什么顺序调用”。评测的重点自然也从“回答质量”变成了“行为质量”。这时候评测场景的定义就变了。一个合格的评测场景至少包含四部分用户目标用户想完成什么任务。环境状态当前有哪些上下文、系统处于什么状态。期望行为Agent 应该调用哪些工具、按什么顺序调用。判定标准工具参数是否合法、结果是否满足用户目标。问题在于要写出这样的场景评测人员不仅要理解业务还要理解每个工具的参数约束、返回值格式、调用前提和常见失败模式。一个工具还好当工具数量到几十个时人工编写场景就完全不可持续了。Agent Seer 的核心判断是工具规格Tool Specification本身就是评测场景的最大信息源。工具的 description 说明了它能干什么parameters 说明了它需要什么、允许什么required 字段暗示了哪些参数是核心约束。把这些信息结构化地读出来再交给场景合成器去推导用户可能提出的任务就能以远低于人工的成本批量生产评测场景。再往深一层说这个思路还解决了另外两个隐患第一人工写的场景容易过拟合。如果评测集是开发团队自己写的模型很容易在评测集上表现好但一遇到真实用户就露馅。从工具规格合成场景天然带有一种“反套路”的性质因为场景生成过程不依赖某一条具体 Prompt 的写法。第二工具更新后场景要同步更新。在传统方式下工具新增了一个参数评测集不会自动跟着变。而基于规格合成的流程里工具规格一变重新合成一遍场景就自动覆盖新能力。所以Agent Seer 真正降低的是 Agent 评测体系的维护成本同时提升了评测覆盖度。它不是来取代人工评测的而是把人工从“重复出题”中解放出来去做更难的场景判断和结果审核。2. 从工具规格到评测场景核心概念拆解要把 Agent Seer 的原理讲清楚先得把三个概念拆开。2.1 工具规格Agent 世界的“接口说明书”在 Function Calling 类的 Agent 架构里工具通常以 JSON Schema 的形式暴露给模型。一个典型工具规格长这样{ type: function, function: { name: weather_query, description: 查询指定城市当前天气支持摄氏度或华氏度, parameters: { type: object, properties: { city: { type: string, description: 城市名称如 北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius } }, required: [city] } } }这段 JSON 就是工具规格。它包含了模型在决定是否调用工具时需要知道的一切工具名字、功能描述、参数约束、必填项。Agent 的推理过程很大程度上就是“读规格 → 理解能力边界 → 决定调用”。2.2 评测场景给 Agent 出的“应用题”评测场景不是简单的一句用户问题而是一个完整的任务设定。在 Agent Seer 的语境下评测场景通常包含用户指令或目标描述。初始环境或上下文。预期工具调用序列。评价指标。它和传统 NLP 评测里的“问题-答案”对最本质的区别在于答案不是一段文字而是一条行为路径。这也是为什么合成评测场景比合成问答对要复杂得多——你不能只生成问题还要生成对 Agent 行为的预期。2.3 合成评测场景从规格推导任务“合成”在这里指的是通过规则或模型从工具规格中推导出用户可能产生的任务需求再为这些任务补充环境状态和期望行为。这里要区分三种场景生产方式方式成本覆盖度更新速度主要风险人工编写高依赖个人经验覆盖有限慢主观、过拟合、不全面模型自由生成中依赖模型知识可能偏离工具能力中幻觉、工具调用不可执行基于工具规格合成低对齐工具能力边界覆盖系统化快场景可能偏“工具导向”缺少真实用户多样性Agent Seer 属于第三种。它的优势不是“生成更多场景”而是“生成更对得上的场景”——每个场景都绑定具体的工具能力不会出现“模型编了一个工具根本做不到的任务”这种尴尬情况。2.4 为什么叫“Seer”Seer 是“预见者”的意思。这个名字其实点出了这个系统的另一个价值在 Agent 真正执行任务之前就预见到它可能面对的各种调用路径包括正常路径、边界路径和错误路径。它不是事后分析 Agent 的表现而是提前把评测场景铺好让 Agent 的每一步都有据可查。这种“先见之明”正是评测体系最需要的。3. Agent Seer 的整体架构四个层次各司其职从工程实现的角度看Agent Seer 可以拆成四个层次。理解这个分层比理解某一段具体代码更重要因为它是你后续扩展和改造的基础。3.1 规格理解层这一层负责把原始工具规格JSON Schema、OpenAPI 文档、甚至自然语言文档解析成结构化的内部表示。它要解决的关键问题包括提取工具名、描述、参数约束。识别工具之间的潜在关联比如“查天气”和“定闹钟”看似无关但在“明天早上提醒我带伞”这个任务里就需要组合。处理参数之间的依赖关系比如“城市”和“国家”二选一。3.2 场景推导层这是整个系统的核心。它基于规格理解层产出的结构化信息生成候选评测场景。实现方式有两种路线规则路线通过模板和枚举组合参数生成大量确定性场景。优点是可控缺点是场景会比较机械。模型路线把工具规格作为上下文交给 LLM让模型生成自然、多样的用户任务。优点是场景真实度高缺点是可能产生幻觉。混合路线先规则枚举构造骨架再用 LLM 润色成自然语言。这是目前工程上比较稳妥的做法。3.3 约束校验层LLM 生成的场景不一定可执行。这一层负责用确定性规则校验场景的合法性。典型校验包括场景中需要用到的工具是否存在于工具集。用户指令涉及的任务是否真的能被当前工具集完成。期望行为中的工具参数是否符合规格约束。场景描述是否包含明显矛盾。3.4 评测执行层校验通过的场景进入评测执行流程。Agent 在模拟环境中执行任务系统记录工具调用轨迹、参数合法性、任务完成度等指标最终生成评测报告。整个架构的核心思想可以概括为“规格 → 场景 → 校验 → 评测”四步闭环。工具规格更新后四个步骤可以自动串联形成“规格驱动”的持续评测体系。4. 环境准备与工程接入如果你也想在自己的 Agent 项目里落地“从工具规格合成评测场景”的思路不需要一开始就搭建一个完整平台。一个最小可用的工程原型只需要以下几样东西。4.1 运行环境Python 3.9 及以上版本推荐 3.10。一个可调用的 LLM API用于场景生成不限定厂商。已有的 Agent 工具规格文件格式为 JSON 或 JSON Schema。如果接入的是 OpenAI 风格 Function Calling工具规格格式天然兼容。4.2 依赖库建议使用以下 Python 库pip install jsonschema openai其中jsonschema用于工具参数约束的校验openai用于调用 LLM 生成场景如果使用其他厂商 SDK替换即可。需要说明的是本文代码是“思路演示”级别的参考实现重点讲解工程流程并非某个官方 SDK 的完整封装。版本号请以实际安装为准。4.3 准备工具规格文件为了后续演示我们先准备一个包含三个工具的规格文件// 文件路径tools.json { tools: [ { type: function, function: { name: query_weather, description: 查询指定城市当前天气, parameters: { type: object, properties: { city: { type: string, description: 城市名 } }, required: [city] } } }, { type: function, function: { name: create_reminder, description: 创建提醒事项, parameters: { type: object, properties: { content: { type: string, description: 提醒内容 }, time: { type: string, description: 提醒时间ISO 格式 } }, required: [content, time] } } }, { type: function, function: { name: search_nearby_places, description: 搜索城市周边指定类型的地点, parameters: { type: object, properties: { city: { type: string, description: 城市名 }, category: { type: string, description: 地点类型如餐厅、医院 } }, required: [city, category] } } } ] }这个文件虽然简单但已经包含了后续演示所需的全部元素单工具场景、多工具组合场景、必填参数约束。5. 核心实现工具规格解析与场景合成下面我们分步实现一个最小可运行的 Agent Seer 工程原型。5.1 工具规格解析模块第一步把原始的tools.json解析成结构化字典供后续模块使用。# 文件路径tool_spec_parser.py import json from typing import Any, Dict, List def load_tool_spec(spec_path: str) - List[Dict[str, Any]]: 加载工具规格文件。 支持两种形态 1. 包含 tools 字段的包裹结构 2. 直接是工具数组 with open(spec_path, r, encodingutf-8) as f: raw json.load(f) if isinstance(raw, dict) and tools in raw: return raw[tools] if isinstance(raw, list): return raw raise ValueError(无法识别的工具规格格式) def normalize_tool_meta(tools: List[Dict[str, Any]]) - Dict[str, Dict[str, Any]]: 将 OpenAI Function Calling 格式的工具列表 转换为以工具名为 key 的摘要字典。 result: Dict[str, Dict[str, Any]] {} for item in tools: fn item.get(function, item) name fn.get(name) if not name: continue result[name] { description: fn.get(description, ), parameters: fn.get(parameters, {}), required: fn.get(parameters, {}).get(required, []), } return result if __name__ __main__: tools load_tool_spec(tools.json) meta normalize_tool_meta(tools) for name, info in meta.items(): print(f[{name}] {info[description]}) print(f 必填参数: {info[required]})运行这段代码你会看到三个工具的名字、描述和必填参数都被提取出来了。这层虽然简单但它是后续所有步骤的基础——如果这里没有把规格结构统一后面合成模块就要面对各种格式兼容问题。5.2 场景合成模块第二步把工具规格摘要交给 LLM生成评测场景。这里的关键是提示词的设计。好的提示词应该完成三件事明确输出格式、约束场景可执行性、要求覆盖不同类型场景。# 文件路径scenario_synthesizer.py import json from typing import Any, Dict, List, Callable SYNTHESIS_PROMPT 你是一名 Agent 评测场景设计师。 请根据下面的工具规格合成 {num} 个评测场景。 工具规格 {tool_spec} 每个场景必须是 1. 用户能够自然提出的真实任务。 2. 仅依赖上述工具即可完成。 3. 包含多样化的难度至少一个单工具场景、一个多工具组合场景、一个边界输入场景。 4. 期望行为中的工具调用必须符合工具规格的参数约束。 请严格输出 JSON 数组每个元素包含 - task: 用户指令 - env: 初始环境描述 - expected_tool_calls: 期望的工具调用序列数组每个元素为 {{tool: 工具名, arguments: {{...}}}} - difficulty: easy / medium / hard 不要输出任何额外文字。 def build_tool_spec_text(meta: Dict[str, Dict[str, Any]]) - str: 把工具摘要转为适合放进 Prompt 的文本。 lines [] for name, info in meta.items(): lines.append(f- {name}: {info[description]}) lines.append(f 参数: {info[parameters]}) return \n.join(lines) def synthesize_scenarios( meta: Dict[str, Dict[str, Any]], llm_func: Callable[[str], str], num: int 8, ) - List[Dict[str, Any]]: 调用 LLM 生成评测场景。 llm_func 是外部注入的 LLM 调用函数便于替换模型或模拟。 tool_spec_text build_tool_spec_text(meta) prompt SYNTHESIS_PROMPT.format(numnum, tool_spectool_spec_text) raw_output llm_func(prompt) # 防御性处理截取第一个 [ 到最后一个 ] 之间的内容 start raw_output.find([) end raw_output.rfind(]) if start -1 or end -1: raise ValueError(LLM 输出中未找到 JSON 数组) scenarios json.loads(raw_output[start:end 1]) return scenarios这段代码有几个细节值得注意llm_func采用依赖注入的方式方便在测试阶段用模拟函数替换真实模型调用。对 LLM 输出做了防御性截取避免模型输出前后夹杂文字导致 JSON 解析失败。提示词明确要求“期望行为必须符合工具规格参数约束”这是降低后续校验成本的关键。5.3 场景约束校验模块LLM 生成的内容不能直接信。第三步用确定性规则校验每个场景里的工具调用是否真的符合规格。# 文件路径scenario_validator.py import json from typing import Any, Dict, List from jsonschema import validate, ValidationError def validate_one_scenario( scenario: Dict[str, Any], meta: Dict[str, Dict[str, Any]], ) - List[str]: 校验单个场景返回错误信息列表。 空列表表示校验通过。 errors [] expected_calls scenario.get(expected_tool_calls, []) # 必须至少有一个期望调用 if not expected_calls: errors.append(场景缺少 expected_tool_calls) for call in expected_calls: tool_name call.get(tool) if tool_name not in meta: errors.append(f未知工具: {tool_name}) continue args call.get(arguments, {}) param_schema meta[tool_name][parameters] # 检查必填参数 for required_param in meta[tool_name][required]: if required_param not in args: errors.append( f工具 {tool_name} 缺少必填参数: {required_param} ) # 使用 jsonschema 做参数合法性校验 try: validate(instanceargs, schemaparam_schema) except ValidationError as e: errors.append(f工具 {tool_name} 参数不合法: {e.message}) return errors def filter_valid_scenarios( scenarios: List[Dict[str, Any]], meta: Dict[str, Dict[str, Any]], ) - List[Dict[str, Any]]: 过滤出通过全部约束校验的场景。 valid [] for idx, sc in enumerate(scenarios): errors validate_one_scenario(sc, meta) if errors: print(f[场景 {idx}] 校验失败: {errors}) else: valid.append(sc) return valid这一步是工程上最容易被忽视、但价值最高的地方。确定性校验可以把“模型幻觉”和“规格不符”的场景挡在评测集之外保证最后进入评测流程的每一条场景都是可执行、有依据的。5.4 编排完整流程最后把三个模块串起来形成一条完整的“规格 → 场景 → 校验”流水线。# 文件路径run_pipeline.py import json from tool_spec_parser import load_tool_spec, normalize_tool_meta from scenario_synthesizer import synthesize_scenarios from scenario_validator import filter_valid_scenarios # 模拟 LLM 调用函数。 # 实际项目中替换为真实的模型 API 调用即可。 def mock_llm(prompt: str) - str: return json.dumps( [ { task: 北京明天天气怎么样, env: 用户在北京想提前知道明天天气以便安排出行, expected_tool_calls: [ { tool: query_weather, arguments: {city: 北京}, } ], difficulty: easy, }, { task: 帮我查一下上海有哪些不错的餐厅并定一个明早提醒去试试, env: 用户周末准备去上海旅游, expected_tool_calls: [ { tool: search_nearby_places, arguments: {city: 上海, category: 餐厅}, }, { tool: create_reminder, arguments: { content: 去上海尝试新餐厅, time: 2025-06-01T09:00:00, }, }, ], difficulty: hard, }, ] ) def main() - None: tools load_tool_spec(tools.json) meta normalize_tool_meta(tools) # 1. 合成 scenarios synthesize_scenarios(meta, llm_funcmock_llm, num2) print(f合成场景数: {len(scenarios)}) # 2. 校验 valid_scenarios filter_valid_scenarios(scenarios, meta) print(f通过校验场景数: {len(valid_scenarios)}) # 3. 输出评测集 with open(eval_scenarios.json, w, encodingutf-8) as f: json.dump(valid_scenarios, f, ensure_asciiFalse, indent2) print(评测集已写入 eval_scenarios.json) if __name__ __main__: main()这个编排脚本展示了完整的最小闭环。实际项目中你需要把mock_llm替换成真实的模型调用并把eval_scenarios.json接续到你的 Agent 评测执行引擎上。6. 评测执行与效果验证评测集生成之后下一步就是把它跑起来。一个标准的执行流程是把场景注入模拟环境 → 让 Agent 完成任务 → 对比实际工具调用序列和期望调用序列 → 计算指标。6.1 指标设计对于工具调用型 Agent建议至少跟踪以下指标指标含义计算方式任务成功率Agent 是否完成了用户目标完成数 / 总场景数工具选择准确率实际调用的工具是否与期望一致正确工具调用数 / 总调用数参数合法率调用参数是否符合工具规格合法参数调用数 / 总调用数路径效率是否以最少步骤完成任务实际步数 / 期望步数场景覆盖度评测集对工具调用路径的覆盖比例已覆盖路径 / 规格推导出的总路径其中“场景覆盖度”是 Agent Seer 这类方案独有的优势指标。传统人工评测很难回答“工具的所有能力都被测过了吗”而基于规格合成的流程可以枚举参数组合和调用顺序形成覆盖率报告。6.2 运行验证的三种方法如果你已经搭好了最小原型可以按下面的顺序验证效果第一规格解析验证。运行python tool_spec_parser.py确认每个工具的 description 和 required 参数被正确解析。第二场景合成验证。把mock_llm替换成真实 LLM 调用运行python run_pipeline.py观察生成的场景质量。重点看三点任务描述是否自然、工具调用是否符合规格、组合场景是否合理。第三端到端评测验证。把生成的eval_scenarios.json接入实际 Agent 执行环境跑一轮评测检查任务成功率和参数合法率是否符合预期。6.3 如何判断生成质量合成场景不是越多越好质量判断应该从三个维度出发可执行性场景中的期望调用是否真的能被工具规格支持。这是硬性标准不达标就应该被校验模块过滤掉。多样性是否覆盖了单工具、多工具组合、边界参数、典型失败路径等不同类别。多样性不足说明提示词或规则需要调整。难度分布是否有合理的 easy / medium / hard 比例。如果全是简单场景评测就失去了区分度。如果你的评测集出现“生成 100 条校验过滤掉 60 条”的情况先不要急着怪模型。更可能的原因是工具规格本身描述不清晰或者提示词对约束的强调不够。这时候优先优化工具规格的 description往往比调模型更有效。7. 常见问题与排查思路在实际落地过程中下面几个问题是出现频率最高的。问题现象可能原因排查方式解决方案LLM 生成的场景大量校验失败工具规格描述不清晰模型无法准确理解参数约束打印校验错误信息统计失败类型优化工具 description明确参数边界和取值枚举生成场景全是单工具调用提示词没有强约束组合场景比例检查生成结果的任务复杂度分布在提示词中显式要求多种难度或增加规则模板兜底场景内容与业务脱节工具规格过于抽象缺少业务上下文对比规格描述和真实用户请求在工具描述中补充典型使用场景和示例JSON 解析失败LLM 在 JSON 前后输出了解释性文字查看原始输出确认截取逻辑是否生效强化防御性截取或使用结构化输出模式评测执行时 Agent 无法复现期望路径场景的期望调用序列是“理想路径”但 Agent 有自己的合理路径对比 Agent 日志和期望序列区分硬性约束必调工具和软性约束可替代路径工具更新后旧场景不再适用评测集没有与工具规格同步重建检查工具变更日志工具规格变更时触发场景重新合成保留历史版本对比这里最值得单独说的是第二类问题。LLM 在生成场景时天然倾向于生成简单、直观的任务因为这类任务最容易编。你的提示词必须明确写“至少包含一个需要组合多个工具的场景”甚至可以把工具两两组合的列表直接喂给模型让它基于这些组合去生成任务。这样能显著提升组合场景的产出率。另一个容易踩坑的地方是“期望调用序列”的粒度。如果你把期望序列定义得太死Agent 只要换一个工具顺序就会被判失败定义得太松评测又失去了约束力。工程上的折中方案是把期望拆成“必须完成的子目标”和“推荐的调用顺序”两层。子目标用于计算任务成功率调用顺序用于计算路径效率分。这样既不会误伤合理的 Agent 行为也能识别出绕远路的情况。8. 最佳实践与工程建议基于“从工具规格合成评测场景”这一思路的落地经验这里给出几条工程建议。8.1 工具规格是评测质量的上限这是整套方案里最重要的一个判断。Agent Seer 的思路决定了工具规格写得越好合成出来的评测场景质量越高。所以落地这个方案之前先把工具规格本身做一次治理。每条 description 至少应该包含功能边界、典型使用场景、参数取值说明、常见的失败条件。一个写得好的工具规格不只是给模型看的也是在给评测场景合成器提供高质量素材。8.2 坚持“确定性优先生成式辅助”场景合成的过程中能用规则解决的问题就不要交给模型。比如参数组合的枚举、必填项校验、工具可达性判断这些都应该是确定性代码。LLM 只负责做它擅长的事把参数组合转化为自然、合理的用户任务描述。这种分工能最大限度降低幻觉风险。8.3 评测集要做版本管理基于工具规格合成的评测集应该和代码、工具规格一样纳入版本管理。每次工具更新就重新合成一轮评测集并和上一版做 diff。这样你能回答一个关键问题这次工具变更到底让 Agent 的能力边界发生了哪些变化评测集本身就是一份可追溯的“能力资产”。8.4 合成场景必须配合人工抽检不要让合成流程完全无人值守。建议保留一个抽检环节每轮合成后人工抽查 5% 到 10% 的场景主要看任务描述的自然度和期望行为的合理性。抽检结果反过来可以用于优化提示词和工具规格描述形成一个持续改进的循环。8.5 安全边界与合法性合成评测场景时要注意几个边界不要生成绕过工具权限控制的评测场景比如让 Agent 调用未授权接口。涉及用户数据、隐私信息的场景要使用脱敏数据。评测环境必须与生产环境隔离避免评测过程产生真实副作用。工具规格中包含敏感能力时评测集本身也要做访问控制。8.6 从“场景数量”转向“路径覆盖”很多团队评估评测集质量时只看数量。但有了基于规格合成的能力之后更值得关注的是覆盖度规格推导出的所有合理调用路径中评测集覆盖了多少。数量多但大量重复的评测集价值远不如一个精心覆盖了所有关键路径的小评测集。9. 总结与后续学习方向Agent Seer 这个方向的核心贡献是把 Agent 评测场景的生产方式从“人工出题”推进到了“规格驱动自动出题”。它的关键链路是四步解析工具规格、推导评测场景、约束校验、执行评测。这四步环环相扣工具规格既是起点也是质量上限。这篇文章讲清楚了三个层面的内容概念层面工具规格、评测场景、合成评测场景三者的关系。原理层面Agent Seer 如何用“规格 → 场景 → 校验 → 评测”的闭环降低出题成本。工程层面一个最小可运行的 Python 实现以及落地过程中常见的坑。如果你正准备在自己的 Agent 项目里搭评测体系建议从最小的闭环开始先整理一份工具规格写一个规格解析器再加一个调用 LLM 的场景合成脚本最后补上约束校验。跑通这个流程之后再逐步加入覆盖度分析、版本管理和人工抽检机制。后续值得深入的方向有三个一是多工具组合场景的系统化枚举二是评测集与工具规格的自动联动更新三是合成场景从“行为校验”向“结果质量”扩展——边跑评测边定义更丰富的判定标准。这些方向本质上都在围绕同一个问题展开如何让 Agent 的能力边界被可量化、可持续、可信赖的方式测量清楚。建议把这篇文章收藏备用当你需要搭建 Agent 评测体系时按“规格解析 → 场景合成 → 约束校验 → 评测执行”的路径走一遍会比从零开始摸索高效很多。