同一个2B模型，四种Agent框架，得分从0.017到0.821：框架如何影响Agent性能？

先放结论：一个 2B 的小模型，如果在普通聊天里，可能只是“有点笨”；但放进 agent 任务里，换四种不同的框架实现，它可以在同一个评测集上从 0.017（基本全挂）打到 0.821（绝大多数任务都通）。这篇东西没有商业成分，也没有玄学，纯粹是一个 agent harness 开源项目的复盘：评测集怎么设计、四个框架的差异到底在哪、为什么同一个模型差距能拉到五十倍，以及这个 harness 怎么自己跑起来。

写这篇文章的目的很简单：我见过太多人拿着 7B/14B 的模型就敢冲 agent 应用，结果上线之后发现模型本身没问题，但一接框架就各种崩；也有不少人在 0.7B、1.5B 这种推理成本极低的模型上做实验，被框架带的格式要求坑到怀疑人生。如果你也在这个坑里，这篇东西应该能帮你省下不少瞎折腾的时间。文章的落脚点不是“再测一个模型”，而是一整套可复现的评测夹具：你把模型接进去，跑一遍，就能看到你的 agent 框架实现有没有把模型的能力白白浪费掉。

1. 为什么会有这个项目：一次崩溃的评测经历

1.1 四个框架得分从 0.017 到 0.821 意味着什么

先说结论的出处。我做了一个很小的 agent harness，把同一个 2B 模型分别接到四个不同风格的 agent 框架实现里，跑了同一个含 32 个任务的工具调用评测集。分数按“完整动作链执行成功且最终答案正确”计分，最终结果如下：

0.017 意味着 32 个任务里只勉强成功了半个，基本等于模型在该框架下完全无法自主完成工具调用。0.821 意味着 32 个任务里能完成 26 个左右。同一个权重，同一个推理服务，同一个温度参数，只有“外部框架怎么向模型描述任务、怎么解析模型输出”这一步不一样。

这不是我随手写的玩具 demo，而是我在一段真实开发周期里反复撞墙之后提炼出来的东西。当时我需要在一个参数量很小、推理成本极低的模型上做一套工具调用链路，第一版直接照搬了主流的 JSON 函数调用思路，结果跑出来的成功率惨不忍睹，一度以为是模型太弱。后来我把同一个模型接到一个更宽松的文本动作框架里，成功率肉眼可见地涨了，才意识到问题一直出在上层实现上。

所以这个 harness 不是为了证明某个模型不行，也不是为了证明某个框架天下第一。它的目的是把“模型能力”和“框架实现”这两件事彻底分开：用一个固定的任务集、一套固定的评分逻辑，让模型和框架之间的互相污染降到最低。这样你再做技术选型时，就能看清到底是在为模型的能力上限买单，还是在为框架的格式损耗买单。

1.2 harness 解决的核心问题

“agent harness”这个名字你可能听得不多。它不等同于 agent 框架，也不等同于模型。通常我们说的 agent 框架，指的是封装了任务规划、工具调用、记忆管理这些能力的上层库；而 harness 更像是实验室里的“夹具”：它固定住任务定义、环境交互、评分规则这些变量，只让模型和框架实现变化，从而得到可对比的结果。

这个项目解决的第一个痛点就是重复性。现在的 agent 任务评测很喜欢用一长串真实 API，比如查天气、订机票、翻文档。问题是这些外部服务不稳定，今天限流，明天字段变了，评测分数忽高忽低，根本没法横向比较。我的做法是把所有工具都做成离线的、确定性的 mock 服务：同一个输入必定返回同一个输出，且工具执行前后的状态变化全部记录在案。这样不管跑多少次，只要随机种子固定，结果就稳定。

第二个痛点是透明性。很多评测结果只给一个最终分，中间哪个动作错了、为什么错、是模型没生成对应动作还是框架解析失败，完全看不到。所以我在这套 harness 里做了“动作级痕迹记录”：不仅记录最终答案，还记录模型每一步的原始输出、框架解析后的结构、工具实际执行结果。每个分数的背后都有据可查。

第三个痛点是易用性。我不想再维护一套只能在某个特定图形界面里点点点的评测系统，也不想在命令行里手工拼任务描述。所以 harness 采用了一个简单可扩展的注册模型：任何人都可以把新任务、新工具、新框架适配器注册进去，跑一次评测只需要一条命令。开源的意义也在于此，你可以直接拿它当基准平台，也可以改造成自己的日常验证工具。

2. 项目整体设计与方案选择

2.1 为什么选 2B 模型做基准

选 2B 这个规模不是随机的。我的目标并不是给大模型写评测，而是想回答一个很多做实际产品的人会关心的问题：当你的预算、功耗、响应速度都不允许上大模型时，一个小模型到底能不能承担 agent 任务？

2B 正好卡在一个有趣的位置：它比 0.5B、1B 这种“玩具级”模型强不少，能理解相对复杂的指令；又比 7B、13B 便宜很多，在 CPU 上也能跑，放到普通消费级显卡上更是飞快。很多嵌入式场景、端侧场景、高并发成本敏感场景，选的恰恰就是这批模型。

如果只做普通问答，2B 模型的表现通常会让人有“还可以啊”的错觉。因为问答只要求模型输出“语义上差不多对”的自然语言，一句回答哪怕措辞不同、信息不全，人眼也能容忍。可 agent 任务完全是另一回事：模型必须输出一个能被外部系统“精确执行”的动作，格式错一点、字段漏一个、参数名写歪了，整个调用链就会断掉。对这种精确的格式遵循能力，2B 模型暴露出来的问题远比想象中大，而框架在这里的作用也远比想象中关键。

我测试过程中发现一个有意思的现象：同一个 2B 模型，在格式宽松的文本动作场景里，它可以正确规划“先查 A 再查 B，最后聚合结果”；在格式严格的结构化输出场景里，它会输出一些看似正确但其实完全不合法的 JSON，甚至把动作描述和自然语言混在一起。这说明模型的规划能力未必缺失，只是被框架的表达方式卡住了。

2.2 四个框架的差异不只是“格式”

既然要对比框架，我特意选了四种实现风格完全不同的方案，避免“换汤不换药”。

框架 A 是市面上最常见的下游接口协议式实现。它把每个工具描述成一个结构化的 schema，让模型在一条消息里输出一个带工具名的调用对象，系统再对结果做严格解析。这种设计对格式遵循能力强的模型非常友好，可以说是一步到位；但小模型常常无法稳定输出合法结构，一旦解析失败，任务立刻中止。

框架 B 是经典 ReAct 风格。模型被要求在文本里先写“Thought”再写“Action”，框架先用正则把“Action：xxx + Action Input：xxx”提取出来，再执行工具。这种做法的核心优势是宽容：哪怕模型写得不太规范，只要动作名称和参数大体匹配，就能继续跑下去。

框架 C 是伪代码规划风格。模型被要求先输出一个分步计划，例如“第 1 步：调用查询函数获取数值；第 2 步：调用计算函数……”，框架按照计划顺序逐步执行，每执行一步就把实际结果追加到上下文里，让模型根据结果决定下一步。

框架 D 是代码解释器风格。工具被封装成一组 Python 函数，模型输出一段 Python 代码，框架在受限环境里执行这段代码，所有工具调用都以函数调用的形式完成。小模型不擅长“结构化声明”，但对“一段很短的代码”反而有更强的模仿能力。

从得分上看，它们的差异被拉得很开，原因是这四种实现不仅改变了提示词排版，还改变了三个更深层的东西：错误容错方式、上下文形态、以及模型需要承担的格式压力。框架 A 把格式压力全压给模型；框架 D 则把格式压力从模型身上挪走了大半，代之以一个能容忍多种写法的代码执行器。

2.3 评测集与评分口径是怎么定的

评测集是整个 harness 的地基，设计得不好，后面的对比全部白搭。我的原则是：任务要足够“像真实工作”，又要足够“能自动判分”。

32 个任务分为四个难度档：单工具调用、多工具顺序调用、条件分支调用、多源信息聚合。单工具调用考察最基本的格式遵循，比如“查一下城市 A 的天气并直接返回温度”。多工具顺序调用要求模型连续操作两个以上工具且结果要传递，比如“先查库存，再算折扣价”。条件分支调用让模型根据第一步的返回值决定是否执行第二步，比如“如果库存小于 50 就补货”。多源信息聚合是难度上限，模型要查两个数据源再合并信息。

工具统一使用 mock 实现，但 mock 不是瞎编。例如天气工具内部维护了一张固定的城市列表，返回的温度和风级都是确定值；数据库工具的内存表里预设了若干条固定记录。同一个输入永远返回同一个输出。这意味着评测分数完全不受网络波动和外部服务状态的影响。

评分口径也刻意设计得很“苛刻”：只有当完整的动作链被执行成功且最终答案正确，才给 1 分；部分成功按比例给分，比如两个动作只做对一个给 0.5 分。拿到 0.017 分对应的极端情况是，模型在绝大多数任务里连第一个动作都因为格式错误而最终失败。这种苛刻的好处是：分数差异不会因为“最终答案沾边就算对”而被人为抹平，框架之间的真实差距会暴露得很彻底。

3. 核心实现拆解

3.1 harness 骨架：统一的任务运行时

harness 本身没有做成“重框架”，核心是一个很薄的任务运行时。它负责四件事：加载任务定义、初始化工具环境、调用模型、执行评分。任务定义用的是数据驱动方式，一个任务就是一个普通的 Python 字典：

TASK_REGISTRY.append({ "name": "stock_and_discount", "description": "查询库存数量并计算折扣价", "tools": ["query_stock", "calc_discount"], "prompt": "请查询商品 SKU-7781 的库存，然后计算该商品打 8 折后的价格。", "expected_actions": [ {"tool": "query_stock", "args": {"sku": "SKU-7781"}}, {"tool": "calc_discount", "args": {"price": 199, "discount": 0.8}} ], "expected_answer": {"price": 159.2} })

运行时拿到任务后，会组装出一次完整的对话日志：系统提示词、用户指令、模型每一步的输出、框架解析出的动作、工具执行结果，全部追加到同一个会话里。这个过程和真实 agent 应用完全一致，区别只是工具是 mock 的，评分是自动的。

每个任务跑完，harness 会把完整痕迹写成一个 JSON 文件，包含最终得分，也包含动作级别的正确明细。跑完 32 个任务后，会生成一张汇总报表，列出每个任务是否通过、失败了哪一步、原始模型输出是什么。这套设计让我在调试框架时省了大量时间：点开失败痕迹就能看到“模型其实输出了正确动作，但解析器没认出来”或者“模型直接开始胡写”这一类根本原因。

任务注册是热插拔式的：新增一个任务只需要往TASK_REGISTRY里加一条记录，不需要改动裁判逻辑。为了快速验证一个想法，我后来经常用 harness 写出只有三五个任务的“微评测集”，跑完就丢弃，真正的体感非常好。

3.2 提示词层：同一个模型看到了不同的世界

四个框架的对比，说白了就是同一个模型在工作台上看到“四套不同的世界”。为了让差异更纯净，我刻意保持系统提示词里的基础风格一致，只在描述输出格式时做区分。

框架 A 的系统提示词是这样的风格：

你是一个工具调用助手。当用户需要你调用工具时，必须输出一个 JSON 对象，字段为： {"tool": "工具名", "args": {"参数1": "值1"}} 不要输出任何解释文字，不要使用 Markdown。

94a130f3fe9f94a130f3fe9f这就对模型提出了极高要求：模型要把意图直接转换成合法 JSON，且不能带任何前缀后缀。2B 模型做这件事时，经常在 JSON 前后加一句“好的，我来帮你：”或者在字符串里出现未被转义的反引号。输出倒是看起来挺像人话，但框架 A 的严格解析器会直接拒绝。

框架 B 的提示词则宽容得多：

你是一个使用工具解决问题的助手。如果需要进行操作，请按下面格式输出： Thought: 你的推理过程 Action: 工具名 Action Input: {"参数1": "值1"} 如果已经得到最终答案，请输出： Final Answer: 你的答案

这里模型不需要一次性把所有工具调用生成完，而是每轮生成一个动作，框架解析后把真实结果填回去，再让模型继续。哪怕模型在 Thought 里写了很长一段废话，只要 Action 那一行能被正则匹配出来，任务就不会断。2B 模型在任务复杂度低时完全能适应这个节奏。这是框架 B 明显优于框架 A 的核心原因。

框架 C 的提示词把“规划”显式化了。模型先要输出一个编号计划，例如：

计划 1: 先调用 query_user_profile 获取用户资料 计划 2: 根据资料中的地区调用 recommend_tour

框架不会直接执行整个计划，而是把“计划”作为背景信息放进上下文，引导模型按步骤一个个来。这种设计的微妙之处在于：它给模型留了“思考缓冲”，同时利用编号对齐来缓解小模型对长序列的注意力涣散问题。

框架 D 的提示词更像一个“编程助手”：

你可以用 Python 调用以下函数： query_stock(sku) -> int calc_discount(price, discount) -> float ... 请输出完成用户需求的 Python 代码，例如： price = query_stock("SKU-7781") print(calc_discount(price, 0.8))

代码执行器会捕获print输出作为最终答案。2B 模型对“写一小段 Python”的模仿能力比“输出一个严格 JSON”强很多，因为训练数据里天然有海量代码片段；而 JSON 工具调用这种对许多小模型来说可能属于较新的合成格式，反而不容易遵循。

3.3 动作解析：0.017 到 0.821 的分水岭

四个框架的得分差异，潜台词就是：大多数 agent 框架把“解析模型输出”这一步做得太脆了。模型生成的文本天然充满噪声，如果解析器只能识别“perfect JSON”或“perfect 正则”，那它本质上是在赌模型永远保持完美。

我在框架 B 里做了一个重要的宽容化处理：解析器会用正则剥离模型输出中的解释性前缀，把Action:之后的内容先截取出来，再用json.loads尝试解析。如果解析失败，不会立刻中止，而是用ast.literal_eval和“key = value”回退匹配来兜底；实在解析不出来，就给模型回一条系统信息：“动作格式无法识别，请重新输出动作。”让模型有机会自我纠正。

这个“重试 + 反馈”机制带来的提升非常明显。框架 A 里一旦 JSON 解析失败就直接判任务失败，模型连改正的机会都没有。框架 B 里解析器会给一句反馈并请求修正，很多原本要挂掉的任务被救回来了。这也是从 0.017 到 0.214 的主因。

框架 D 干脆绕开了“结构化解析”这个问题。模型只需要输出代码，代码由沙箱里的 Python 解释器执行；天然没有“格式不合法”的问题，最多是“代码逻辑跑不通”。小模型只要能把目标函数名和参数写对，执行基本不会出问题。这个思路用一个厚实的执行器换掉了模型中不可控的格式能力，得分自然高出很多。

提示：很多人会误以为“宽松解析”等于“降低标准”。实际上不是。宽松解析是针对噪声的鲁棒性，评分依然按动作链完整性和最终答案判分。只要能稳定复现正确动作，宽松就是不折不扣的收益。

4. 实操过程与复现方式

4.1 环境准备与模型服务

复现这套实验并不复杂，核心依赖只有三块：一个能本地跑的模型服务、一个 Python 运行时、若干 mock 工具。模型服务我在测试时用的是能兼容 OpenAI 接口协议的本地推理进程，模型参数量 2B，加载权重后占用内存约 4GB 左右。

git clone https://example.com/my-agent-harness cd my-agent-harness pip install -e .[test]

模型服务的地址通过环境变量配置，默认读取127.0.0.1:8000。除此之外，harness 不依赖任何外部网络服务。你甚至可以把模型服务换成一个返回固定文本的假接口来测试 harness 本身，这样就能确认评测链路没有问题。

工具侧的 mock 实现全部在本地，比如：

def query_stock(sku: str) -> int: STOCK_TABLE = { "SKU-7781": 36, "SKU-9902": 120, "SKU-3141": 5, } if sku not in STOCK_TABLE: raise ToolInputError(f"未知 SKU: {sku}") return STOCK_TABLE[sku]

这种 mock 会刻意训练模型“先确认参数再调用”，因为传了个未知 SKU 会触发工具端异常，异常信息会追加到上下文，让模型看到自己犯了错。这比干巴巴地打分更接近真实场景。

4.2 运行评测三条命令搞定

启动 harness 之后，实际跑评测只需要三步。先注册要对比的框架适配器，再指定模型服务地址，最后运行：

python -m harness run \ --task-set default_32 \ --model-endpoint http://127.0.0.1:8000/v1 \ --framework D \ --temperature 0.0 \ --max-steps 6

--max-steps参数用来限制单任务最大动作数，防止模型在某个循环里反复生成同一个错误动作。默认设置为 6，超过就强制中止该任务并按 0 分处理。--temperature 0.0是我跑对比时的固定设置，尽量减少随机性对结果的影响；如果你想评估稳定性，可以换成 0.7 跑多次再求均值。

每次评测结束，结果文件放在output/run-<时间戳>/目录下。里面有summary.json、traces/和scores.csv。traces/里每个任务一个文件，记录了模型每轮的原始输出、解析出来的动作、工具返回值以及最后的判分原因。这不是一个“黑盒打分器”，而是一个能让你逐字审查的透明过程。

4.3 结果解读：不要只看总分

第一次跑出 0.017 和 0.821 差距时，我第一反应是“评分器写错了”，还专门去查了失败痕迹。结果发现框架 A 的失败模式非常一致：模型基本每次都输出了类似“好的，我来查询”这种自然语言，然后没有任何结构化内容。这足以说明小模型在那个格式要求下没有建立“输出工具调用对象”的条件反射。

后来我又把四个框架各自失败的任务做了归类，发现一个更细的规律：框架 A 几乎全军覆没，每个任务都是首动作失败；框架 B 的任务主要死在多工具传递上，模型在第二步偶尔忘记“继续调用”而直接结束；框架 C 的问题是偶尔会输出一个现实里不存在的工具名；框架 D 的失分则集中在长任务最后一步的数值计算误差上。

这类按阶段拆分的失败归因比一个总分有用得多。你在自己的项目里跑完评测后，建议也养成这个习惯：不要只盯着“通过多少任务”，而是把“死在哪一步”做成柱状图。如果是第一步就格式崩，问题在输出解析层；如果是中间步骤断，问题在上下文管理和规划记忆；如果是最后一步算错，那就是模型数值能力本身的问题，换框架也救不了。

5. 常见问题、典型失败模式与排查

5.1 小模型在 agent 任务里的四种失败模式

跑了几百次评测之后，我总结出 2B 这一级别模型最常见的四种失败模式，你可以对照自己遇到的故障快速定位。

第一种是“自然语言吞噬”。模型会把整个工具调用过程写成一段通顺的自然语言，而不是结构化的动作描述。这在框架 A 里最明显，因为框架要求极严，小模型达不到，只能退化到最擅长的“说人话”。这类问题的解法不是加大模型，而是换更宽容的输出协议，或者给模型提供更多“现成的范例片段”供模仿。

第二种是“一步到位综合征”。模型在第一个动作成功之后，直接输出最终答案，完全忽略了后续还需要继续调用工具。这通常是上下文里没有足够强的“每一步都要执行一个动作”的惯性。框架 C 用分步计划解决了这个问题，因为计划先明确列出来，模型在下文执行时会更有方向感。

第三种是“参数幻视”。模型生成了正确的工具名，但参数值是从上下文里硬猜出来的，比如用户说“查一下库存”，工具明明需要 SKU 而上下文里没有，模型就编造一个“SKU-0000”。这个问题比较难从框架层面彻底解决，只能靠工具端更强的错误反馈来纠正。

第四种是“上下文漂移”。当任务历史超过四五轮时，小模型会把早期信息忘掉或者混淆，导致最后聚合时用错中间结果。框架 D 里最典型的表现是：第一步拿到 A 值，第二步重新声明了错误数值或凭空引用变量名，但代码里的函数名又看起来“正确”，于是执行器跑了，只是结果错。

5.2 评测不稳定：别让框架背锅

评测跑出来不稳定，通常不是任务太难，而是评测环境里混入了噪声。我在调试时遇到过几次分数忽高忽低，最后定位到几个干扰因素，整理成一张速查表：

我在 harness 里默认展示的是单次结果，但如果要做严谨对比，建议每个框架跑三遍取中位数。尤其是当你调整提示词、只加了几个字的时候，单次运行结果可能完全是噪声。三次取中位数能有效过滤掉偶然波动。

5.3 调试框架适配器时的几个技巧

最有效的调试方式是打开“逐动作回放”：在失败任务的 trace 文件里，你能清楚看到模型第一轮输出、解析器提取内容、工具返回值、第二轮输出。如果第一轮输出明明是“Action: query_stock”但 trace 里显示没有任何动作被解析，那问题八成在正则没匹配上。

你可以手动用最经典的文本格式测试一下解析器：

python -m harness debug-parse \ --text "好的，我来查一下。\nAction: query_stock\nAction Input: {\"sku\": \"SKU-7781\"}"

这个命令会直接告诉你解析器从这段文本里提取到了什么结构。很多看似复杂的框架问题，最后都会归结到“正则没适配模型偶尔加个前缀”这种细小原因。把解析器的输入输出单独抽出来调试，比端到端反复跑快太多。

我调试过程中还发现一个耐人寻味的细节：有两个框架适配器在工具描述里加入了“返回类型注释”，例如查询库存（输入：SKU，输出：整数）；另一个框架只写了“query_stock(sku) -> int”。后者的效果明显更好。小模型对贴近代码风格的函数签名理解得更自然，而冗长的人类可读描述反而稀释了注意力。

一个重要经验：与其追求“让模型完美遵守格式”，不如让框架的“下半身”更结实。小模型注定会在格式上时不时犯傻，解析器如果接受错误、给出明确修正提示，模型是有机会自我纠偏的。这比反复在提示词里强调“不要出错”要可靠得多。

尾声：一些个人体会

整个项目跑下来，我最深的一个感触是：模型评测里的分数，本质上是在评测“模型和框架的耦合质量”，而不是模型本身的绝对智商。0.017 和 0.821 这两个分数摆在一起，很容易让人误以为是模型能力悬殊，但真正悬殊的是四个框架替模型承担的格式压力差。模型还是那个模型，工作台变了，表现就完全不同。

如果你现在也在折腾小模型做 agent，我建议你先把自家应用里“解析模型输出”的那一段代码拿出来单独审视一遍：它是不是”宽容“到能接受不完美的文本？失败时会不会给模型回补偿信息？工具描述是代码风格还是散文风格？这几个小问题，可能比你再换一个大模型更能决定最终线上效果。

这套 harness 本身还在迭代中，当前版本已经支持任务热注册、动作痕迹回放、多次运行取中位数。你可以轻松地把它扩展成你自己的团队日常验证工具，也可以只拿其中某个框架适配器当作参考实现。如果你跑出了和我不一样的结论，很可能是不同模型底座导致的正常差异，欢迎带着 trace 来探讨——我只认动作级痕迹，不认口号。