★ FEATURED ARTICLE 1. 为什么我要自己搭一套 Agent 评测框架模型厂商的宣传页我看了太多几乎每一家都在说自己的 Agent 能力“业界领先”。但真把同一个任务丢给不同模型跑结果经常打脸有的模型在演示视频里行云流水实际跑三步就开始胡编工具参数有的模型宣传里“长程任务稳定”结果第五轮就开始忘记最初的目标。这种落差不是个别现象而是当前 Agent 领域的常态。问题的根源在于大部分公开评测要么是单轮问答要么是精心挑选的“展示型任务”跟真实业务里那种多步骤、带工具调用、需要状态维护的活儿完全不是一回事。你拿一个“帮我查天气”去测 Agent跟拿一个“从三个数据源拉数据、做交叉校验、生成报告并归档”去测得到的结论可能完全相反。所以我花了大概三周时间搭了一套自己的 Agent 真实任务评测框架。核心目标很明确用可复现的任务集、可追踪的执行链路、可归因的评分机制把“谁真行”这件事从玄学变成数据。这套框架不依赖任何特定厂商的 SDK理论上可以接任何支持工具调用的 Agent 实现。它适合谁如果你正在选型 Agent 底座模型、正在做 Agent 应用开发、或者单纯想搞清楚自己搭的 Agent 到底几斤几两这套思路都能直接抄。不需要你有很深的评测学背景但需要你对 Agent 的基本工作方式有概念——知道什么是工具调用、什么是执行轨迹、什么是任务终止条件。我先把整体设计讲清楚再逐层拆解任务设计、执行追踪、评分归因这三个核心模块最后给一份我踩过的坑和排查清单。全程都是实操向参数和判断依据我都会写明白。2. 评测框架的整体设计与选型考量2.1 为什么不用现成的评测平台市面上不是没有 Agent 评测工具但我在选型阶段试了几个之后放弃了原因有三个。第一任务不可控。很多平台的评测集是固定的你没法针对自己的业务场景定制任务。我要测的是“多源数据交叉校验”这类任务平台里根本没有对应类别。第二追踪粒度不够。大部分平台只告诉你“成功/失败”不告诉你失败在哪一步、是工具调用错了还是推理链断了。这对定位问题毫无帮助。第三评分不可归因。一个任务失败了到底是模型能力问题、工具描述问题、还是任务本身设计有歧义现成平台给不出这个答案。所以我的选择是自己搭一套轻量框架核心逻辑自己写只复用通用的执行和日志组件。这样任务集、追踪、评分三个环节全部可控。2.2 框架的三个核心模块整套框架我拆成三块每块职责单一方便单独迭代任务设计模块定义任务的结构、工具集、成功判据、难度分级。这是评测的地基任务设计不好后面全是白搭。执行追踪模块记录 Agent 每一步的输入、输出、工具调用、耗时、token 消耗。这是归因的证据链。评分归因模块基于追踪数据从结果正确性、过程合理性、效率三个维度打分并给出失败原因分类。这三块的关系是任务设计决定“考什么”执行追踪决定“怎么记录”评分归因决定“怎么判”。任何一块偷懒结论都不可信。2.3 技术栈选择与理由我最终用的技术栈比较朴素理由是评测框架本身要足够稳定不能引入额外变量组件选型理由执行语言Python 3.11Agent 生态最成熟工具库最全任务定义YAML JSON Schema人类可读方便版本管理校验严格追踪存储SQLite JSONL单机够用查询方便不引入外部依赖评分逻辑纯 Python 规则 少量 LLM 辅助规则可解释LLM 只用于语义类判断可视化简单的 HTML 报告不搞复杂前端够看就行这里有个关键取舍评分环节我坚持“规则优先LLM 辅助”。纯 LLM 打分看起来省事但它的评分本身就不稳定你没法用它来评测另一个模型。规则打分虽然写起来麻烦但可复现、可解释出了问题能查。提示如果你的任务涉及大量主观判断比如文案质量规则打分确实不够用。这时候可以用 LLM 打分但必须固定评分模型的版本和 prompt并且对同一批任务跑多次取一致性否则评分本身就成了噪声源。3. 任务设计评测框架的地基3.1 任务结构怎么定义一个任务在我的框架里是一个 YAML 文件包含以下字段task_id: cross_source_validation_001 category: multi_source_reasoning difficulty: 3 goal: 从三个数据源拉取指定指标交叉校验后生成报告 tools: - fetch_api - query_db - read_file - write_report success_criteria: - type: output_contains value: 校验通过 - type: tool_called tool: write_report min_times: 1 max_steps: 15 timeout_seconds: 120这里每个字段都有讲究。category用于分类统计difficulty是人工标注的难度等级1-5success_criteria是成功判据列表max_steps和timeout_seconds是硬性约束。为什么要有 max_steps因为有些 Agent 会陷入无限循环反复调用同一个工具。没有步数上限评测会卡死。我一般设 15 步复杂任务设 25 步。为什么 success_criteria 是列表而不是单个布尔值因为真实任务的成功往往是多维的。既要结果对又要过程合理。拆成多个判据评分时可以做部分给分更能反映能力差异。3.2 任务难度分级的设计逻辑难度分级不是拍脑袋定的我按四个维度综合评估步骤数需要多少步才能完成。3 步以内算简单8 步以上算难。工具数需要调用多少种不同工具。1 种简单3 种以上难。依赖关系步骤之间是否有强依赖。线性依赖简单有分支和回退的难。歧义程度任务描述是否有多种合理解读。无歧义简单有歧义难。四个维度各打 1-5 分取平均后四舍五入得到最终难度。这套标准是我自己摸索的不一定科学但至少保证了同一难度等级的任务在体感上差不多。3.3 任务集的构建原则我构建任务集时遵循三条原则这三条是踩坑踩出来的。第一任务要来自真实场景不能是玩具。我最初设计了一批“计算 11”这种任务结果所有模型都满分完全区分不出能力。后来改成“从订单表里找出异常订单并生成处理建议”区分度立刻上来了。第二任务要有明确的成功判据。模糊的任务没法评分。比如“帮我分析一下数据”这种任务什么叫分析完了没法判。必须改成“找出销售额环比下降超过 20% 的品类并列出 Top 3”。第三任务集要覆盖不同能力维度。我目前的任务集分五类单工具调用、多工具串联、条件分支、错误恢复、长程状态维护。每类至少 5 个任务总共 25 个起步。任务太少统计结论不可靠。注意任务集一旦定下来就不要在评测过程中随意修改。改了任务就等于换了考卷前后结果没法比。如果确实要加任务单独跑一轮别混在一起。3.4 工具集的设计与陷阱工具集是任务设计里最容易出问题的地方。我踩过的坑包括工具描述太模糊导致模型不知道怎么用、工具参数太多导致模型填错、工具返回值格式不统一导致模型解析失败。我的经验是工具设计要遵循“最小必要”原则每个工具只做一件事不要设计“万能工具”。参数名要自解释比如start_date比sd好。返回值统一用 JSON字段名固定不要有时返回字符串有时返回对象。工具描述里写清楚什么时候该用、什么时候不该用。举个例子我有个query_db工具最初描述只写了“查询数据库”结果模型经常在不该查的时候查。后来改成“当需要获取结构化数据时使用参数为 SQL 查询语句仅支持 SELECT”误用率明显下降。4. 执行追踪让每一步都有据可查4.1 追踪什么数据执行追踪模块记录 Agent 每一步的完整信息。我记录的字段包括字段说明step_index第几步timestamp时间戳input_context这一步的输入上下文含历史model_output模型的原始输出parsed_action解析后的动作工具调用或最终回答tool_name调用的工具名tool_params工具参数tool_result工具返回结果latency_ms这一步耗时token_usagetoken 消耗这些数据全部落到 SQLite同时每步追加写一份 JSONL 作为原始日志备份。SQLite 用于查询分析JSONL 用于出问题时回溯原始记录。为什么要记录 input_context因为很多失败是上下文管理问题。比如模型在第 8 步忘了第 2 步的关键信息你只有看 input_context 才知道是上下文被截断了还是模型自己没注意。4.2 追踪的实现方式追踪的实现有两种思路侵入式和非侵入式。侵入式是在 Agent 代码里埋点每一步主动上报。优点是数据全、精度高缺点是要改 Agent 代码不同 Agent 实现要分别适配。非侵入式是包一层代理拦截 Agent 和模型、Agent 和工具之间的通信。优点是不用改 Agent缺点是有些内部状态抓不到。我最终用的是混合方案工具调用层用非侵入式代理拦截模型调用层用侵入式埋点。这样既不用大改 Agent又能拿到关键的模型输入输出。具体实现上工具代理就是一个装饰器包住每个工具函数def traced_tool(func): def wrapper(*args, **kwargs): start time.time() result func(*args, **kwargs) latency (time.time() - start) * 1000 trace_logger.log_tool_call( tool_namefunc.__name__, paramskwargs, resultresult, latency_mslatency ) return result return wrapper模型调用层的埋点稍微麻烦点需要在每次调用模型前后记录。我用的是统一的模型客户端封装所有模型调用都走这个封装埋点只写一次。4.3 追踪数据的清洗与对齐原始追踪数据不能直接用来评分需要先清洗和对齐。我遇到的主要问题有三个。问题一时间戳不对齐。不同组件的时钟可能有偏差导致步骤顺序错乱。解决方法是统一用单调时钟并且在每个步骤开始时打一个序号排序以序号为准时间戳只作参考。问题二工具返回值格式不一致。有的工具返回字符串有的返回字典有的返回列表。评分逻辑没法统一处理。解决方法是在追踪层做归一化所有工具返回值统一转成{status: success/error, data: ..., error: ...}格式。问题三模型输出解析失败。有些模型输出的工具调用格式不规范解析器解析不出来。这种情况我单独标记为parse_error不当作正常步骤但计入失败统计。提示追踪数据的清洗规则要固定下来写进文档。否则不同人跑评测清洗方式不一样结果没法比。4.4 追踪数据的存储与查询SQLite 表结构我设计得比较简单主要就三张表runs每次评测运行、steps每一步、tool_calls工具调用明细。查询用 SQL 就够了不需要上复杂的分析工具。一个典型的查询是“找出所有失败任务中工具调用错误占比最高的任务类别”SELECT t.category, COUNT(*) as total, SUM(CASE WHEN s.parsed_action tool_error THEN 1 ELSE 0 END) as tool_errors FROM steps s JOIN runs r ON s.run_id r.run_id JOIN tasks t ON r.task_id t.task_id WHERE r.status failed GROUP BY t.category ORDER BY tool_errors DESC;这种查询能快速定位问题集中在哪类任务、哪个环节。比看单个任务的日志高效得多。5. 评分归因从“失败”到“为什么失败”5.1 三维评分模型我的评分模型分三个维度每个维度独立打分最后加权汇总。结果正确性权重 50%任务目标是否达成。这个维度用 success_criteria 逐条判定每条判据给 0 或 1 分最后算通过率。过程合理性权重 30%执行路径是否合理。包括工具选择是否正确、参数是否合理、是否有冗余步骤、是否有无效重试。这个维度需要一些规则判断比如“调用了不存在的工具”扣分“同一工具连续调用 3 次以上且参数相同”扣分。效率权重 20%步数和耗时。步数越少、耗时越短得分越高。但要注意效率不能单独看一个任务 3 步完成但结果是错的效率分再高也没意义。所以效率分只在结果正确的前提下才计入。三个维度的权重是我根据业务需求调的。如果你的场景更看重结果可以把结果权重提到 70%如果更看重过程可控性可以把过程权重提上去。5.2 失败归因的分类体系评分归因最有价值的部分不是打分而是失败原因分类。我把失败原因分成六大类失败类型说明典型表现理解错误模型误解了任务目标做了完全无关的操作规划错误任务拆解不合理步骤顺序错、漏步骤工具选择错误选错了工具该查库的时候调了 API参数错误工具参数填错日期格式错、字段名错上下文丢失忘了之前的信息重复问已经问过的执行超限超过步数或超时陷入循环这个分类体系是我迭代了三版才定下来的。第一版太粗只有“成功/失败”第二版太细分了二十多类统计时根本用不上第三版合并成六类刚好够用。归因的实现方式是规则匹配加人工复核。规则匹配能覆盖大概 70% 的情况剩下的 30% 需要人工看追踪日志判断。我一般每周花半小时复核一批失败案例把新的失败模式补充到规则里。5.3 评分结果的可视化评分结果我生成一个简单的 HTML 报告包含三部分总览各模型在各类任务上的得分对比用表格展示。明细每个任务的得分、失败原因、关键步骤截图。趋势同一模型在不同难度任务上的得分曲线。报告不追求好看追求信息密度。我试过用一些可视化库做花哨的图表后来发现表格加少量折线图最实用查问题最快。5.4 评分归因的常见陷阱评分归因这块我踩过几个大坑写出来供参考。陷阱一把模型能力和框架能力混为一谈。同一个模型换个 Agent 框架得分可能差很多。所以评测结论必须注明“在 XX 框架下”。我现在的报告里模型名和框架名是并列的。陷阱二忽略随机性。大模型输出有随机性同一个任务跑一次和跑三次结果可能不同。我的做法是每个任务至少跑 3 次取平均分同时记录方差。方差大的任务单独标记说明这个任务本身不稳定。陷阱三评分标准漂移。评测跑多了评分标准会不自觉地放松或收紧。解决方法是把评分规则写死在代码里每次评测用同一套规则改规则要单独记录版本。6. 实操过程从零跑通一次完整评测6.1 环境准备与依赖安装环境准备比较简单Python 3.11 加几个基础库pip install pyyaml jsonschema sqlite-utils httpx不需要装任何 Agent 框架的 SDK因为我的框架是通过统一接口对接 Agent 的。你只需要实现一个AgentAdapter类把 Agent 的调用封装成run(task) - trace的形式。6.2 任务集的准备与校验任务集放在tasks/目录下每个任务一个 YAML 文件。写完后用 JSON Schema 校验一遍确保字段完整、类型正确import yaml from jsonschema import validate with open(schema/task_schema.json) as f: schema json.load(f) for task_file in Path(tasks).glob(*.yaml): with open(task_file) as f: task yaml.safe_load(f) validate(task, schema)校验能挡掉大部分低级错误比如漏写 success_criteria、difficulty 超出范围等。这一步别省省了后面跑起来才发现问题更浪费时间。6.3 执行一次评测的完整流程完整流程分五步加载任务集从tasks/读取所有任务按类别分组。初始化 Agent实例化待测 Agent注入工具集。逐任务执行对每个任务调用 Agent 的run方法同时启动追踪。收集追踪数据执行结束后从追踪存储里拉出这次运行的所有步骤。评分与归因对追踪数据跑评分逻辑生成报告。这五步我封装成一个evaluate.py脚本命令行调用python evaluate.py --agent my_agent --tasks tasks/ --output reports/run_001跑 25 个任务每个任务 3 次总共 75 次执行大概需要 20-40 分钟取决于模型响应速度。6.4 一次真实评测的数据记录我拿两个模型跑了一轮任务集 25 个每个任务跑 3 次。结果如下模型结果正确性过程合理性效率综合得分模型 A0.720.680.810.72模型 B0.640.750.690.68单看综合得分模型 A 略高。但拆开看模型 A 结果正确性高但过程合理性低说明它经常“蒙对”——结果对了但过程乱七八糟。模型 B 反过来过程规范但结果差说明它规划能力好但执行能力弱。这种细分结论只看宣传页是绝对看不出来的。而且这个结论直接影响选型如果你的场景对过程可控性要求高比如金融、医疗模型 B 可能更合适如果只看最终结果模型 A 更划算。6.5 评测结果的解读方法拿到评分报告后我一般按这个顺序看先看失败任务的分布集中在哪类任务、哪类失败原因。如果 80% 的失败都是“参数错误”那问题可能在工具描述不在模型。再看方差大的任务这些任务本身可能设计有问题需要重新审视。最后看同一模型在不同难度上的得分曲线。如果难度 1-2 得分很高难度 3 断崖式下跌说明这个模型的能力边界在难度 3 附近。提示评测结论不要只看一次。模型会更新框架会迭代任务集会扩充。我一般每两周跑一次完整评测记录趋势。单次结果只能说明当下趋势才能说明方向。7. 常见问题与排查技巧实录7.1 任务执行卡死怎么办最常见的问题是 Agent 陷入循环反复调用同一个工具。我的处理方式是三层防护第一层max_steps 硬限制超过就强制终止。第二层重复调用检测同一工具连续调用 3 次且参数相同触发警告。第三层超时终止单任务超过 timeout_seconds 强制结束。三层防护下来基本不会卡死。但要注意强制终止的任务要标记为terminated不能算作正常失败否则会污染失败原因统计。7.2 工具调用参数错误的排查参数错误是最常见的失败原因。排查时我按这个顺序看工具描述是否清晰模型知不知道这个参数该填什么参数类型是否明确是字符串还是数字格式有没有说明有没有示例给一两个正确参数的例子能大幅降低错误率。我实测下来给工具描述加一个example字段参数错误率能降 30% 左右。这个投入产出比很高。7.3 评分结果与直觉不符怎么处理有时候评分说某个任务成功了但你看追踪日志觉得不对劲。这种情况我一般先怀疑评分规则再怀疑任务设计最后才怀疑模型。评分规则的问题通常是 success_criteria 写得太宽松。比如只判定了“输出包含关键词”但模型可能是瞎蒙的。这时候要加过程判据比如“必须调用过 write_report 工具”。任务设计的问题通常是任务本身有歧义。同一个任务不同人理解不一样评分自然对不上。这时候要重新写任务描述消除歧义。7.4 常见问题速查表问题可能原因排查方法任务卡死循环调用看追踪日志找重复步骤参数错误率高工具描述不清检查工具 schema 和示例评分与直觉不符判据太宽松复核 success_criteria结果方差大任务有歧义重读任务描述找歧义点上下文丢失历史被截断看 input_context 长度工具选择错误工具描述重叠检查工具职责是否清晰7.5 我踩过的三个大坑坑一任务集太小。最初只设计了 8 个任务跑出来的结论波动很大今天 A 模型高明天 B 模型高。后来扩到 25 个结论才稳定。任务集至少 20 个起步这是底线。坑二忽略 token 消耗。一开始只看结果和步数没记 token。后来发现有些模型是靠“疯狂输出”蒙对的token 消耗是别人的三倍。现在 token 消耗是必记字段效率分里也占一定权重。坑三评分规则写死在代码里但没版本管理。改了一次评分规则前后结果没法比。现在评分规则单独放一个文件每次改动记版本号报告里注明用的哪个版本。8. 框架的扩展方向与个人体会这套框架目前跑得比较稳但我还在持续迭代。几个正在做的扩展方向一是加入多 Agent 协作场景的评测现在只测单 Agent二是加入成本维度把 token 消耗换算成实际费用让选型更有经济依据三是把任务集做成可插拔的方便不同业务场景替换。如果你也想搭一套我的建议是先从 5 个任务、1 个模型跑通全流程别一上来就搞大而全。跑通之后你会发现最难的不是写代码而是设计出真正有区分度的任务。任务设计的能力直接决定评测的价值上限。另外评测框架本身也要评测。我每隔一段时间会拿一个已知能力的模型跑一遍看结果是否符合预期。如果不符合说明框架本身出了问题得先修框架再测别的。最后分享一个我用了很久的小技巧把每次评测的追踪数据存下来别删。这些数据是宝贵的资产能用来分析模型行为模式、优化工具设计、甚至训练自己的小模型。我最早的追踪数据现在还在用回头看能发现很多当时没注意到的规律。
阅读完成 · 觉得有帮助？
