程序化工具调用：Agent 一次请求跑完几百个工具，省的是什么-平芜编程栈

程序化工具调用：Agent 一次请求跑完几百个工具，省的是什么

原文：Factory Research - 《Droid 1.0: Building a Frontier Harness》（https://factory.com/news/frontier-harness）

一、先说结论：省的不是钱，是请求次数

我们平时写的 Agent 循环基本是这样一个节奏：模型输出一个工具调用，框架执行，把结果塞回消息列表，再请求一次模型。一个任务里有 10 个工具调用，就是 10 次以上的模型请求。

Factory 这次发布的 Droid 1.0 换了个做法，叫程序化工具调用（Programmatic Tool Calling，PTC）：不逐个调用工具，而是让模型先写一段 JavaScript，把"要怎么调用工具"这件事写成代码，然后一次执行完。原文的定义很短——PTC 是让 Agent 写一个程序去调用工具，模型可以先把整个流程想清楚，写出代码，然后一次性端到端执行。

这句话里最值得琢磨的是"一次性"。因为在逐个调用的模式下，每一轮请求都要把系统提示、工具定义、历史记录、之前的工具结果重新发一遍。调用越碎，重复发的东西越多。

二、两个真实例子，量级差别有多大

原文给了两个企业内部场景的实测，对比的是"直接工具调用"和"Script 模式"。

场景	直接调用	Script 模式
Linear 批量清理任务（移动并验证 151 个 issue）	312 次工具调用，约 36 次模型请求，约 310 万输入 token	2 次模型请求，约 6.1 万 token
CI 扫描（547 个 run 里的 5384 个 desktop job）	550 次工具调用，估计 59 到 187 次请求	2 次请求，每次 60 个并发

第二个例子更值得注意：550 次工具调用跑完，进入模型上下文的结果不到 0.1%，模型最后只看到五个数字的摘要，其中包含 41 个 failed jobs。

这就是 PTC 和传统工具调用的本质差别。传统模式下，每一次工具结果都必须回灌到对话里，因为那是模型判断下一步的依据。而 PTC 模式下，原始文件、搜索结果、日志这些都留在程序内部当变量，模型收到的只有程序打印出来的那部分输出。

三个理由，原文讲得很直白：

上下文干净。模型只拿到程序的输出，不用吞掉几百条原始结果。
请求次数少。一个程序跑多次调用，固定成本只付一次。
可靠性高。判断和循环在代码里确定性地执行，不依赖模型每一步都判对。

第三点容易被低估。如果你要遍历 500 个文件、挑出提到某个词的那几个，这件事写成代码就是一个 filter，写成 Agent 的多轮推理就是 500 次"这个文件提到了吗"的判断，其中任何一次判错都会污染后面。

三、Script 工具的设计细节，比"写代码调工具"更重要

如果只是"让模型输出代码再执行"，那算不上什么新东西。原文里有几个设计选择，才决定这套东西能不能用在生产环境。

1. 程序拿到的必须是真数据

原文的说法是：程序拿到整个文件和结构化的、带类型的搜索结果，过滤和计数在代码里完成，不消耗 token。

这一点决定了 Script 模式的成本优势。如果工具返回的是被格式化、被截断、被转义过的字符串，那程序里就没法做正经的数据处理，模型还是得把结果读回上下文。

2. 字面文本走原始输入块

文件内容、补丁、命令这些直接放在原始输入块里，不走转义字符串。原文的理由是省 token，也减少格式错误的调用。

写过工具调用的人应该都踩过这个坑：把一个 2000 行的文件塞进 JSON 字符串里，既要转义引号和换行，又容易把 JSON 本身的格式搞坏。原始输入块绕过了这个问题。

3. 编辑结果返回短摘要

程序内部做一次文件编辑，返回的摘要和直接编辑一样短，文件内容不会被重新粘回上下文。

4. 长任务不让模型干等

程序最多等 5 分钟，超时就把当前已有的输出交回；也可以后台启动、立即返回。配套的是三个专用工具：查看、等待、停止。后台任务完成时，harness 主动唤醒模型，而不是让模型反复问"好了吗"。

这个设计针对的是一个很现实的延迟问题。跑一次全量测试可能要几分钟，如果模型必须同步等待，这几分钟就完全浪费；如果改成轮询，又白烧请求。

5. 启动时只加载两个工具

原文提到，工具定义从 11 个降到 2 个，很少用的工具按需加载。整份启动 prompt 从 20887 token 降到 13055 token，降幅 37%。其中工具定义从 15798 降到 8528。

这个数字和 PTC 没有直接关系，但它说明了同一件事的两面：Agent 的每一轮请求都在为"固定开销"付钱，固定开销越小，同样的钱能买到的有效工作越多。

四、一个单测修复的回放，看清时间花在哪

原文给了同一任务、同一模型（GPT-6.1 Sol，high reasoning）的两种跑法的逐轮计时。任务是修一个失败的单元测试。

直接调用：10 次模型调用 + 15 次工具调用，总耗时 56.8 秒。Script 模式：5 次模型调用 + 同样 15 次工具调用，总耗时 41.6 秒，提前 15.2 秒。

拆开看就明白了。直接调用里，每次模型调用之间通常只夹 1 到 2 个工具调用，而工具本身执行很快（读文件 14 毫秒、git status 218 毫秒），真正的时间在模型调用上。Script 模式下，第一轮那个 Script 用 421 毫秒一口气做完了 TodoWrite、读两个文件和 git status，第二轮用 1.25 秒做完 TodoWrite 加打补丁；于是模型调用从 10 次减到 5 次，模型调用总耗时从 42.3 秒降到 28.0 秒。

所以 PTC 的收益结构和"工具快不快"关系不大，和"工具调用的轮次多不多"强相关。原文的另一个数字印证了这点：Script 模式让 Droid 在 Claude Opus 5.5 上成本降低 15%，而节省集中在其中 12.5% 的、工具调用达到 6 次以上的任务上。大多数 Script 都很小，小到省不出多少东西。

这条经验对做 Agent 产品的人很实用：不要为了 PTC 而 PTC，先看看你的任务里有没有"多次短调用"的模式。

五、自己动手最小验证

下面这段是最小验证脚本，用来量化"轮次削减"能带来多少请求数和 token 的下降。它不依赖任何特定框架，只统计请求数。

# 自拟示意，非官方实现，用于验证请求数变化# 场景：读 200 个文件，找出包含关键词的文件名importglob,os FILES=glob.glob("repo/**/*.ts",recursive=True)[:200]KEY="deprecated"# 方案 A：逐个工具调用 —— 每个文件一次 read_file，每批一次模型请求defturn_by_turn(batch_size=2):requests,tool_calls,tokens=0,0,0foriinrange(0,len(FILES),batch_size):requests+=1# 每批结果回灌后，模型要再请求一次batch=FILES[i:i+batch_size]tool_calls+=len(batch)# 粗略估算：每个文件内容都进上下文，一个文件按 800 token 计tokens+=sum(800for_inbatch)+3000# 3000 是每轮固定的指令与历史开销returnrequests,tool_calls,tokens# 方案 B：程序化工具调用 —— 一个 Script 里循环读文件，只返回命中的文件名defprogrammatic():requests=1# 一次模型请求写出程序tool_calls=len(FILES)tokens=3000+sum(len(os.path.basename(f))forfinFILES)//4returnrequests,tool_calls,tokensforname,fnin[("A 逐个调用",turn_by_turn),("B 程序化调用",programmatic)]:req,tcs,tok=fn()print(f"{name}: requests={req}, tool_calls={tcs}, est_tokens={tok:,}")

三个参数值得解释一下：

batch_size控制每次请求里塞几个工具调用。设成 2 是偏乐观的估计，实际框架通常更保守。
方案 A 的 token 估算里，每个文件按 800 token 计入上下文，这是关键项：同一份文件内容在后续每轮请求里都会被重复发送，真实开销比这个模型更高。
方案 B 的 token 只算程序打印出来的文件名，因为原始内容没有进上下文。

跑完你会看到请求数从约 100 降到 1，token 差一个数量级以上。数量级结论是可靠的，具体数字取决于你的文件大小和系统提示长度，应当自己按实际场景重算。

需要把口径说清：上面的比例来自我按原文描述写的估算脚本，不是官方实测。原文给的两个企业场景数字（312 次调用压到 2 次请求、550 次调用压到 2 次请求）才是官方口径。

六、收益的边界在哪

原文的基准测试里，Droid 1.0 在 Terminal-Bench 4 上，用 GPT-6.1 Sol 时分数比 Codex 高 3.5 分、成本低 12%；用 Claude Opus 5.5 时比几款对比 harness 高 3.0 到 7.6 分。全文总括的说法是最多高效 20%。

这些数字的前提要说清楚：每个任务跑 3 次 trial，只统计两边都通过的任务，成本按各家的列表价计算。PTC 不改变模型的推理能力，它改变的是"同样的推理要花多少次请求"。

所以 PTC 有明确的适用边界：

适合：批量读、批量搜、批量改，任务里各步骤之间依赖弱，可以写成确定性的程序。
不适合：每一步都必须看结果再决定下一步的探索型任务，写不出稳定的程序，硬写反而更差。
风险：程序跑错了不会自己停下来纠正，一次执行完可能已经改了 50 个文件。所以沙箱要限制住（Droid 的 Script 沙箱自身没有文件、网络、系统访问，打印输出有大小上限），并且要有回滚。

顺带提一个原文里的反向案例，挺有意思：给每个文件的每一行都加行号，让模型不用再通过 shell 去查行号，某一任务上把 Opus 的成本降了 22%；但这让每次读取多出约两行 token，GLM 的成本涨了 8%，Kimi 涨了 32%。同一个"优化"，在不同模型上方向可以相反。工具的 token 成本必须按模型算，不能拍脑袋。