外观
工具按需加载:把工具目录从系统提示词里挪出去
一句话定义: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 内联渲染在对话末尾
│
└─ 模型调用真正的工具三个要点:
- 搜索工具本身不能延迟,否则模型没有办法发现其他工具;
- 被引用的工具定义仍要放在请求的
tools数组里,服务端靠它做检索与展开,只是不进上下文; - 系统提示词里列出延迟工具的名字和一句话简介,模型才知道该搜什么。
谁在提供这项能力
| 提供方 | 打开方式 |
|---|---|
| Anthropic Messages API | 在 tools 里加 tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119,其余工具标 defer_loading: true |
| OpenAI | Responses 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。
不适合:工具少且每个请求都用得上;延迟加载还没在所选网关与开源模型上真正实现;任务极短,搜索的往返成本盖过节省。
参考资料
关联词条
- Harness(智能体执行框架)(concept)—— 上下文与工具暴露是 harness 的核心机制
- 从一次 LLM 调用到完整 Harness(concept)—— 每次请求的组成,决定了前缀里能放多少东西
- Pi:极简、开源的终端 AI 编程 Agent(tool)—— 提示词层做减法的对照:4 个工具、不到 1000 token 的系统提示词
- DeepSeek Harness 与 Pi 的架构拆解(comparison)—— 工具注册与插件树的两种组织方式
- 监督比你聪明的 Agent:六个动作与 Lint 倒金字塔(pattern)—— 同一条减法思路:上下文只留当下有用的部分
- 返回 设计模式