Agent Seer：从工具规格自动合成Agent评测场景

这次我们来看一个和“评测 AI Agent 怎么评测”直接相关的技术项目Agent Seer。它的核心不是做一个更强的对话模型而是从工具规格出发自动合成评测场景。简单说给定一个工具或一批工具的规格说明它能生成对应的测试问题、预期调用路径和边界用例用来衡量一个具备工具调用能力的 Agent 到底能不能用对工具、用准参数、处理好异常。这类能力在 LLM 应用测试、RAG 工具调用验证、Agent 回归测试里非常实用。这个项目最值得关注的有几点一是把“评测场景设计”从纯人工变成半自动二是输入结构化工具规格本身就是确定的输入源三是输出可以被复用生成的场景能直接接进评测脚本或测试平台四是面向的是工具调用型 Agent而不是普通聊天模型。本文会从项目定位、技术原理、环境准备、部署启动、功能验证、接口调用、批量任务和排查方法展开帮你在本地或测试环境里把这条链路跑通。如果你正在做 Agent 应用的质量保障或者要给内部工具平台写自动化评测用例这篇文章可以直接收藏。1. Agent Seer 核心能力速览能力项说明项目类型Agent 评测场景合成工具 / 评测数据生成框架核心输入工具规格说明如函数签名、JSON Schema、OpenAPI 定义、docstring核心输出评测场景用户问题、预期工具调用序列、参数取值、边界条件、判断指标主要功能工具规格解析、语义理解、场景生成、场景去重、批量合成是否支持本地部署取决于生成后端使用本地大模型时可完全离线是否支持 API通常以服务方式提供接口具体路径按实际版本确认是否支持批量任务支持对多个工具规格或多条输入批量生成显存/硬件要求由底层大模型决定使用 API 模型时本地只需 CPU 内存使用本地模型时需按模型规格评估启动方式命令行 / WebUI / API 服务按发布包确认适合场景Agent 回归测试、工具调用评测集构建、RAG 管线上线前验证、内部工具平台质量保障需要注意Agent Seer 本身不是一个“跑推理的 Agent”它更像一个“评测素材生产线”。它把工具规格变成能被执行的测试用例你拿这些用例去跑目标 Agent再根据结果判断目标 Agent 的工具调用能力。2. 这个项目解决什么问题手工写 Agent 评测集是一件非常痛苦的事情。第一是成本高一个工具往往要覆盖正常调用、参数缺失、类型错误、超范围取值、空返回、权限不足等多种情况每个工具手写十几个用例几十个工具就是几百条维护成本极高。第二是覆盖不全写的人容易按自己熟悉的路径写漏掉边界情况。第三是更新慢工具规格一变用例就要跟着改人工跟进很容易滞后。Agent Seer 的思路是把这件事拆成两步。第一步理解工具规格第二步根据规格自动生成评测场景。工具规格本身是结构化的里面包含工具名称、功能描述、参数类型、必填项、取值范围、返回值格式等信息这些信息足够支撑一个模型去推导“用户会用这个工具问什么问题”“什么情况下会调错参数”“什么情况下工具应该拒绝调用”。从使用场景来看Agent Seer 适合以下几类团队正在做 Agent 应用开发需要一个可持续更新的评测集企业内部有大量 API 工具想验证 LLM 是否能正确选择和调用这些工具做 RAG 或 MCP 工具接入上线前需要一批标准测试用例想对工具描述文本本身做质量检查看哪些工具因为没有写清楚导致 Agent 用错。边界也要说清楚。Agent Seer 生成的是评测场景不是业务答案也不替代最终的人工审核。对于涉及真实用户数据、版权素材、敏感权限的评测场景生成后必须经过合规审查不能直接把含隐私信息的工具规格或样例提交到外部大模型服务更不能把生成结果直接用于生产环境的无监督决策。3. 技术思路拆解从工具规格到评测场景虽然具体实现要参考项目源码但从“工具规格理解”到“评测场景合成”这条链路业界和该项目的核心思路基本可以拆成四个环节。3.1 工具规格结构化解析输入通常是 JSON Schema 或函数签名例如{ name: get_weather, description: 根据城市名查询当前天气, parameters: { type: object, properties: { city: { type: string, description: 城市中文名例如北京 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius } }, required: [city] } }这一步要做的是把规格转成模型能理解的语义表示同时提取出关键约束必填字段、枚举值、类型、默认值、描述文本。如果工具规格原本就是 OpenAPI 格式还需要做格式归一化。3.2 工具语义理解模型需要理解这个工具“在什么场景下会被调用”“和相似工具的区别是什么”“哪些参数容易混淆”。例如get_weather和get_historical_weather都涉及天气但一个查当前一个查历史对应的用户问题完全不同。如果规格描述不清晰Agent Seer 还可以在合成阶段补一个“工具描述质量问题”的提示这一点对工具平台运营者尤其有价值。3.3 评测场景合成根据理解结果生成一组场景每个场景通常包含{ scenario_id: get_weather_normal_001, tool_under_test: get_weather, user_question: 北京今天多少度, expected_tool_call: { name: get_weather, arguments: {city: 北京, unit: celsius} }, difficulty: normal, edge_case: false }高质量的场景合成不能只生成“正常调用”用例还要覆盖参数缺失、参数类型错误、枚举值外输入、空输入、同义表达、多工具选择混淆、需要拒绝调用的请求等。这些才是评测 Agent 时最容易暴露问题的部分。3.4 去重与校验批量生成后需要对场景做去重和可执行性校验。比如同一个意图被两种问法覆盖时要保留差异更大的那一个再比如生成的 expected_tool_call 参数是否真的符合工具规格要用程序做一次 schema 校验不符合的直接丢弃或打回重生成。4. 环境准备与前置条件Agent Seer 的部署门槛主要由底层大模型决定。如果你打算完全本地化生成需要准备 GPU 或较高配置的 CPU 环境如果你使用云端大模型 API本地只需要一个能跑 Python 脚本或服务的轻量环境即可。4.1 基础环境清单项目建议操作系统Linux / Windows WSL2 / macOS以项目文档为准Python3.10 及以上建议使用虚拟环境依赖管理pip 或 uv避免污染系统环境大模型后端本地模型如 Qwen、Llama 系列或云端 API需有可用密钥磁盘空间至少预留 5-10GB如果下载本地模型则按模型体积预留网络下载依赖和模型需要网络完全离线场景需要提前下载好模型文件4.2 大模型后端的两种选择如果目标是快速验证功能优先接云端 API。这种方式部署简单本地资源占用低适合先跑通流程。如果业务要求数据不出内网或者工具规格涉及敏感信息那就必须用本地模型。本地模型的显存占用取决于模型尺寸和推理框架7B 到 14B 量级的模型在量化后通常 8G 到 16G 显存可以跑但具体数字要以你的实际环境和模型版本为准不要拿其他项目的经验直接套。4.3 工具规格准备这是最容易被忽略的一步。Agent Seer 的输出质量直接依赖输入的工具规格质量。建议先准备 3 到 5 个真实工具的规格格式统一为 JSON Schema 或 OpenAPI。不要一开始就批量导入几百个工具先用小样本跑通确认生成效果后再扩大。5. 安装部署与启动方式先说明这里给出的是通用部署思路具体命令需要以项目仓库的 README 为准。一般流程如下。5.1 拉取代码并创建虚拟环境# 示例实际仓库地址以项目发布页为准 git clone https://example.com/agent-seer.git cd agent-seer python -m venv .venr source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install -r requirements.txt如果项目提供了一键安装脚本也可以直接执行# 示例不同项目脚本名不同 bash install.sh5.2 配置大模型后端找到配置文件例如config.yaml填入模型后端信息llm: provider: openai_compatible # 云端或兼容接口 base_url: https://api.example.com/v1 api_key: sk-xxx model: your-model-name # 如果使用本地模型则配置为 # provider: local # model_path: /models/qwen-7b agent_seer: input_dir: ./tools output_dir: ./scenarios max_scenarios_per_tool: 20 dedup_threshold: 0.85 schema_validation: true配置注意两点API Key 不要硬编码进代码尽量用环境变量读取本地模型路径要确认是否存在启动前先检查模型文件完整性。5.3 启动服务如果项目提供 API 服务模式启动方式通常是# 示例具体端口和参数以项目为准 python server.py --host 127.0.0.1 --port 8000启动后可以先访问健康检查接口确认服务状态curl http://127.0.0.1:8000/health返回正常说明服务已就绪。端口被占用时换一个端口即可例如--port 8001。6. 功能测试与效果验证部署完成后不要直接上大批量任务先按下面的顺序做功能验证。6.1 工具规格输入测试把准备好的工具规格放入输入目录执行单工具合成python cli.py --tool tools/get_weather.json --output output/预期结果是在输出目录下生成一个场景文件。判断成功的标准是输出包含至少一个正常调用场景和一个边界场景场景中的预期参数能通过 JSON Schema 校验描述语言可读不是无意义的模板套话。6.2 场景质量抽检从生成结果中随机抽取 5 到 10 条人工检查以下几点用户问题是否贴近真实使用场景预期工具调用是否合理边界用例是否真的覆盖了规格中的枚举值、必填项、类型约束是否存在重复或相似度过高的场景。如果抽检通过率低于 80%优先检查工具规格描述是否完整。很多情况下不是生成器能力不行而是输入规格本身就含糊。6.3 生成结果校验用程序校验生成场景是否符合工具规格import json import jsonschema with open(tools/get_weather.json) as f: tool_spec json.load(f) with open(output/get_weather_normal_001.json) as f: scenario json.load(f) schema tool_spec[parameters] jsonschema.validate(scenario[expected_tool_call][arguments], schema) print(schema validation passed)通过说明至少参数层面是可执行的。这一步应该做成批量脚本每次生成后自动跑一遍。6.4 结合目标 Agent 做端到端测试Agent Seer 生成的场景最终要用来测 Agent。你可以把生成的 user_question 喂给目标 Agent再把 Agent 实际产生的工具调用和 expected_tool_call 做对比。对比维度包括是否选择了正确的工具参数是否完整参数值是否符合约束面对歧义问题时是否主动澄清面对不应调用工具的场景是否拒绝调用。这一步是判断 Agent Seer 生成场景是否“好用”的关键而不是只看它生成了多少条数据。7. 接口 API 与批量任务如果 Agent Seer 提供服务模式接口能力和批量任务设计是把它接入测试平台的关键。7.1 接口调用示例一个常见的调用方式是提交工具规格异步返回生成结果。结构一般类似import requests url http://127.0.0.1:8000/api/synthesize payload { tool_schema: { name: get_weather, description: 根据城市名查询当前天气, parameters: { type: object, properties: { city: {type: string}, unit: {type: string, enum: [celsius, fahrenheit]} }, required: [city] } }, max_scenarios: 10, include_edge_cases: True } response requests.post(url, jsonpayload, timeout300) print(response.json())返回结果中通常会包含场景列表、校验状态和错误信息。具体字段名以实际接口文档为准。7.2 curl 调用示例curl -X POST http://127.0.0.1:8000/api/synthesize \ -H Content-Type: application/json \ -d { tool_schema: { name: get_weather, description: 根据城市名查询当前天气, parameters: { type: object, properties: { city: {type: string}, unit: {type: string, enum: [celsius, fahrenheit]} }, required: [city] } }, max_scenarios: 10, include_edge_cases: true }7.3 批量任务设计批量任务建议采用“输入目录 输出目录 任务清单”的方式{ batch_name: tool_eval_20250101, input_dir: ./tools, output_dir: ./outputs, max_scenarios_per_tool: 15, validate_schema: true, retry_failed: true }实际执行时每处理一个工具就写一条日志记录开始时间、结束时间、生成数量、校验失败数方便后续回溯。批量任务最容易出现的问题有两个一是某个工具的规格格式异常导致任务中断建议单工具失败不影响整个批次二是生成长时间运行导致请求超时可以把单工具超时时间单独设置失败后自动重试一次。7.4 失败重试建议重试不是简单地把同一个请求再发一遍。建议先看失败原因如果是模型输出格式非法可以带上“上次输出 错误信息”再请求一次如果是工具规格本身有问题直接跳过并记录不要重试。重试次数建议控制在 2 次以内避免浪费接口额度。8. 资源占用与性能观察Agent Seer 的资源占用主要在生成阶段也就是底层大模型推理时。8.1 如何观察显存占用本地模型运行时可以用下面命令观察显存nvidia-smi -l 2观察的重点不是瞬间峰值而是连续生成过程中的稳定占用。如果批量任务把多个生成进程同时拉起显存可能叠加容易出现 OOM。更稳妥的做法是控制并发数先跑一个工具确认显存占用后再逐步调大并发。8.2 CPU 与 GPU 的差异CPU 推理可以跑但速度会明显变慢。如果只是做小样本验证CPU 够用如果要批量生成几百个场景建议用 GPU。显存占用不能用“模型参数量”直接推断因为量化方式、上下文长度、批量大小都会影响实际占用。判断标准只有一个在你自己的机器上跑一次最小用例观察稳定占用。8.3 影响性能的关键参数上下文长度工具规格越长输入 token 越多推理时间越长生成长度场景数量越多输出越长耗时越高并发数并发越高显存压力越大但吞吐并不一定线性提升校验开关开启 schema 校验会多一点 CPU 开销但能显著提高结果可靠性建议保持开启。如果发现生成速度过慢优先降低max_scenarios_per_tool先跑通再用小批量验证速度。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后服务无响应依赖未装全或端口冲突查看启动日志检查端口占用补装依赖更换端口重启生成结果为空工具规格解析失败或模型返回格式非法检查输入 JSON 格式和模型日志修复工具规格增加格式校验和重试schema 校验失败率过高工具规格描述不完整模型无法推断正确参数抽取失败样例对比原规格优化工具 description补充参数示例值批量任务中途卡住单个工具规格异常或超时未处理查看任务日志定位卡住的工具增加单工具超时控制和失败跳过本地模型显存不足模型过大或并发过高观察 nvidia-smi 输出降低并发换量化模型或改用 API 后端API 调用超时单次生成任务耗时长默认超时太短检查请求超时配置调大 timeout或改用异步任务模式生成场景相似度过高去重阈值过低或生成 prompt 缺乏多样性检查去重参数调高去重阈值增加温度或改写 seed这里最值得提醒的是先确认“生成失败”和“校验失败”是两回事。生成失败是模型没产出内容校验失败是产出了但不符合规格。两者的排查方向完全不同前者看模型调用日志后者看工具规格和生成参数。10. 最佳实践与使用建议10.1 先小样本验证再批量扩展第一次使用只跑 1 到 2 个工具规格人工抽检生成质量确认链路稳定后再批量导入。不要一上来就处理几百个工具否则问题会被埋在海量输出里。10.2 工具规格质量要前置管理Agent Seer 的效果上限是工具规格质量决定的。如果发现生成场景质量差不要只调生成参数先去补工具规格里的 description把参数含义、常见取值、边界条件写清楚。一个写得好的工具规格比调十次 prompt 都有效。10.3 生成场景要纳入版本管理生成的评测场景建议和工具规格一起纳入 Git 管理。工具规格变更后重新生受影响场景并做 diff能快速定位行为变化。构建一个“工具规格变更 → 场景重新生成 → 回归测试”的自动化流水线是 Agent 评测长期可维护的关键。10.4 合规与安全边界使用 Agent Seer 时必须注意以下几点工具规格中如包含内部 API 路径、鉴权信息、真实用户数据禁止直接提交到外部大模型服务生成的评测场景如果涉及人脸、声音、隐私信息或版权内容必须先做合规审查再使用评测场景仅用于软件验证和测试不得用于绕过访问控制、制作攻击工具或收集未经授权的数据批量调用 API 时要遵守服务商的使用条款和频率限制输出内容在进入任何自动化流程前建议保留人工抽检环节。10.5 接口服务要控制访问范围如果 Agent Seer 以服务方式对内提供建议把服务绑定到内网地址不直接暴露公网在服务前面加一层鉴权对调用方做控制设置单次请求的工具规格大小限制防止超大输入拖垮服务。11. 总结与下一步Agent Seer 最值得尝试的点是把 Agent 评测场景从人工编写变成了可复用、可批量生成的流水线。它先解决的是“有没有用例”的问题再解决“用例全不全”的问题。对于正在做 Agent 应用质量保障的团队来说先用三到五个真实工具规格跑通全流程是成本最低的验证方式。最先要验证的功能不是生成数量而是生成质量抽检正常场景和边界场景的比例确认预期工具调用能通过 schema 校验。最容易踩的坑有两个一是工具规格描述太差导致生成结果不可用二是不做人工抽检直接把生成结果接入测试流程。后续可以扩展的方向包括把生成的评测场景接入目标 Agent 的自动化回归测试建立工具规格变更触发场景重生成的流水线以及用一段时间内的评测结果反向优化工具规格描述。这条路跑通之后Agent 工具调用的质量保障就不再依赖“今天灵感好多写几条用例”了而是一套可持续迭代的评测基础设施。