Skip to content

工具按需加载:把工具目录从系统提示词里挪出去 ​

一句话定义:Agent 的每次请求都背着一整套工具 schema 走路,哪怕这次一个都用不上;**延迟工具加载(deferred tool loading)**把工具目录移出系统提示词,换成让模型用一个搜索工具按需取用,取到的那一个才在对话里展开。


成本藏在每次请求的前缀里 ​

接三个 MCP(Slack、Notion、Baseten)时,这些服务器提供的全部工具调用 schema 会给系统提示词加上约 14.1 万 token,而且每个请求都要带一次。改成延迟加载后,这一坨变成约 1.3k——差别不在这一轮用没用某个工具,而在前缀本身有多长。

这就是为什么"换个便宜模型"往往不如"少塞点东西"。模型没变、harness 没变,只是把工具的加载时机从"开工前全塞进去"改成"用到时再取"。

省下来的到底是什么 ​

理解收益要回到解码过程。两种模式下,每生成一个输出 token,都要对上下文里所有已缓存的 KV 条目做注意力计算,注意力开销大致是 n × 输出长度,n 是 KV 缓存里的 token 数。

  • 预加载(eager):完整工具 schema 每轮都进前缀。前缀虽然被缓存命中,但缓存本身极大——示例里 n 大约是延迟模式的 100 倍,于是每一个解码步都更贵、更慢。
  • 延迟加载(deferred):前缀只剩工具名和一个搜索工具,短而稳定,命中率更高。取到的 schema 不写回系统提示词,而是渲染在对话末尾,前缀不动,缓存继续有效。

所以省钱和提速是同一件事的两面:前缀小了,每个输出 token 的注意力成本就小了,端到端的请求时间跟着下降。

机制:名字先给,schema 后取 ​

text
请求:  [系统提示词] + [工具名清单 + tool_search]            ≈ 1.3k token
          │
          ├─ 模型判断需要某个工具 → 调用 tool_search
          │
          ├─ 客户端/网关返回 tool_reference(指向匹配的工具名)
          │
          └─ 服务端把完整 schema 内联渲染在对话末尾
                    │
                    └─ 模型调用真正的工具

三个要点:

  1. 搜索工具本身不能延迟,否则模型没有办法发现其他工具;
  2. 被引用的工具定义仍要放在请求的 tools 数组里,服务端靠它做检索与展开,只是不进上下文;
  3. 系统提示词里列出延迟工具的名字和一句话简介,模型才知道该搜什么。

谁在提供这项能力 ​

提供方打开方式
Anthropic Messages API在 tools 里加 tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119,其余工具标 defer_loading: true
OpenAIResponses API 原生支持;Codex 在自家模型上默认启用
Baseten Model APIs开源模型(DeepSeek V4.1 Flash、Kimi K3、GLM 5.3 等)在 Chat Completions / Messages 上给工具加 defer_loading: true,Responses 用 tool_search

按 Anthropic 官方文档,单次请求最多可有 10,000 个延迟工具,每次搜索默认返回 5 个匹配项,可调至 10,000;工具检索的是名字、描述、参数名与参数描述。文档给出的典型多服务器场景(GitHub、Slack、Sentry、Grafana、Splunk)光定义就约 55k token,工具搜索通常能砍掉 85% 以上。

基准结果 ​

Baseten 从 8 个基准里抽了 55 个任务,用 GLM 5.3 在 Claude Code 无头模式下分别跑开、关两种模式:编码类注册三个 MCP,agentic 类只用基准自带的工具。

任务类型成本时间
编码(Terminal-Bench、SWE-bench Verified、SWE-bench Pro v2、DeepSWE v1.1)平均 −62.5%平均 −26.2%
Agentic(MCP-Atlas、AutomationBench、ComplexMCP、Toolathlon-GYM)平均 −51.1%平均 −14.9%

省得更多的两个条件:注册的 MCP 又多又大;完成任务需要的请求多,每一次请求都在省一截输入 token——这也是 agentic 类收益可观的原因。

反例同样重要:Toolathlon-GYM 平均每个任务 68 次工具调用,工具本来就几乎全都要用,预加载反而更划算;DeepSWE 与 MCP-Atlas 的时间略有增加,被判为可忽略,因为成本降幅更大。

网关会悄悄把它关掉 ​

如果 Agent 指向第三方网关来切换闭源与开源模型,延迟加载经常在中间失效:作者指出 Codex 和 Claude Code 在指向第三方开源模型提供方时会关闭这项能力,需要手动重新打开,而且对方必须真的在服务端网关与推理层实现了它。

结果就是这些网关在能力上落后——没有延迟加载,每个注册过的 MCP 的全部 schema 都跟着每次请求回传,其中大量工具根本用不上。

落地要点 ​

  • 保留 3–5 个最常用工具不延迟,省掉每次搜索的往返;
  • 至少保留一个非延迟工具,全延迟的请求会被 API 拒绝;
  • defer_loading 不能和 cache_control 同时用,同一工具上叠加会直接报 400,缓存断点放到非延迟工具上;
  • 工具命名按服务加前缀(github_、slack_),一次搜索能命中一整组;
  • 工具少于 10 个、或每个请求都要用全部工具时,不必上这套机制。

它是减法的一种 ​

Harness 的工程重心正在从加法转向减法:过去用来给模型补充上下文的边界情况与护栏,如今更多是负担。延迟工具加载是这条线上的一个具体动作——把"progressive disclosure"(渐进披露)从文档、技能搬到工具层:先给目录,再给细节。

这条思路在提示词层也有对应做法:AGENTS.md 保持最小,只放项目描述、包管理器、非标准的构建与类型检查命令,其余规则拆进被引用的文件、按需展开,而不是把所有约定都堆在根文件里每次重读。

适用与不适用 ​

适合:注册了多个 MCP 或插件、工具定义总量上万 token 的 Agent;任务链很长、请求数很多的工作流;工具库持续增长的内部 harness。

不适合:工具少且每个请求都用得上;延迟加载还没在所选网关与开源模型上真正实现;任务极短,搜索的往返成本盖过节省。

参考资料 ​

关联词条 ​