关于渐进式披露工具上下文的几种方向讨论

1.当前 agent 的工具调用机制是什么？#

相关概念我在之前的博客里已经重复过很多遍了，不过这里最好还是再重复一遍：我们日常看到的所有 Agent——不管是 Claude code、codex、Cursor 还是别的什么 Harness 框架——其内部的模型都一直，且只会做一件事，即预测并输出下一个 token。所谓调用工具，本质上是模型在某一刻，按照预先约定的格式，吐出了一段结构化的文本。

这是理解后续一切设计取舍的起点。

1
{
2
  "messages": [
3
    { "role": "user", "content": "查询北京天气" }
4
  ],
5
  "tools": [
6
    {
7
      "name": "get_weather",
8
      "description": "查询指定城市的天气",
9
      "parameters": {
10
        "type": "object",
11
        "properties": {
12
          "city": { "type": "string" }
13
        },
14
        "required": ["city"]
15
      }
16
    }
17
  ]
18
}

1
{ "role": "assistant", "content": "好的，我来帮你查一下北京的天气。" }

1
{
2
  "role": "assistant",
3
  "content": null,
4
  "tool_calls": [
5
    {
6
      "id": "call_123",
7
      "name": "get_weather",
8
      "arguments": { "city": "北京" }
9
    }
10
  ]
11
}

1
{
2
  "name": "get_weather",
3
  "arguments": { "city": "北京" }
4
}

1
❌ 文本协议（不注册）：
2
模型输出普通文本 → 本地自己解析 → 判断是不是工具调用 → 校验参数 → 执行
3
↗ 灵活，但可靠性和工程复杂度全由框架承担
4

5
✅ 原生 Tool Calling：
6
Provider 返回正式 tool_calls → 本地直接读取 name、arguments、call_id → 校验授权 → 执行 → 按 call_id 回传结果
7
↗ 可靠，但受限于 Provider 的 JSON Schema 约束

2.渐进式披露，和为什么渐进式披露工具需要独特的工程设计#

1.最正统：Anthropic 的 Tool Search Tool#

A\ 在 2025 年 11 月发布了Tool Search Tool，大致的原理是：首先，客户端仍然需要把完整的工具契约全部发给 Anthropic；但是我们可以把某些没那么必要的工具标注为 defer_loading，被标注的工具不会进入模型的初始长下文。在这种情况下，agent 的初始上下文中只有 Tool Search 和少量的非延迟加载工具。Astropick 将会在服务端维护隐藏的工具目录。

大概的工具契约是这样的：

1
{
2
  "tools": [
3
    {
4
      "type": "tool_search_tool_bm25_20251119",
5
      "name": "tool_search_tool_bm25"
6
    },
7
    {
8
      "name": "learning_create_cards",
9
      "description": "Create learning cards...",
10
      "input_schema": {
11
        "...": "完整严格 schema"
12
      },
13
      "defer_loading": true
14
    },
15
    {
16
      "name": "learning_create_plan",
17
      "description": "Create a study plan...",
18
      "input_schema": {
19
        "...": "完整严格 schema"
20
      },
21
      "defer_loading": true
22
    }
23
  ]
24
}

这里我们假设这个 Agent 是一个学习场景的专用 Agent，我们给它注入的工具有一大堆学习相关的工具，比如制卡之类的；那么当模型需要学习制卡能力的时候，agent 就会调用：

1
{
2
  "name": "tool_search_tool_bm25",
3
  "input": {
4
    "query": "create flashcards from study notes"
5
  }
6
}

Anthropic 在服务端搜索工具目录，返回特殊的 tool_reference：

1
{
2
  "type": "tool_reference",
3
  "tool_name": "learning_create_cards"
4
}

Provider 随后在当前对话位置把这个引用展开成完整工具定义。模型看到真实 schema 后，可以直接产生：

1
{
2
  "type": "tool_use",
3
  "name": "learning_create_cards",
4
  "input": {
5
    "...": "严格参数"
6
  }
7
}

内置搜索在 Anthropic 服务端运行，搜索结果和目标工具调用甚至可以出现在同一个 assistant response 中。客户端只需要执行最终的具体工具。

顺带一提，搜索有两个变体：tool_search_tool_regex_20251119 让模型写 Python re.search() 正则模式来匹配（上限 200 字符），tool_search_tool_bm25_20251119 则接受自然语言查询（上限 500 字符）。两者都会搜索工具名、描述、参数名和参数描述。

那么问题又来了，这种方式会破坏缓存吗？当然不会。这里的关键不是「发现后不改变工具列表」，而是 Anthropic 对 defer_loading 有一套特殊语义：

1
原始缓存前缀：
2
[Tool Search]
3
[System Prompt]
4
[历史消息]
5

6
发现工具后：
7
[Tool Search]
8
[System Prompt]
9
[历史消息]
10
[tool_reference → 展开的真实工具契约]

我们可以看到，完整工具定义是在发现位置追加进去的，没有回头修改最前面的工具前缀。历史消息里出现过的 tool_reference 会被 API 全程展开，所以模型在后续轮次可以直接复用已发现的工具，不需要重新搜索。

这种实现方法的坏处是——强依赖于 Anthropic 这个 Provider，我们是没办法在自己的程序中离开 A\ 去复刻的，因为 A\ 控制了模型推理前的内部处理：

1
我们发送的 tools
2
        ↓
3
Anthropic 分成：
4
- 隐藏工具搜索索引
5
- 模型可见上下文
6
- Tool Calling 严格语法
7
        ↓
8
按需将契约插入对话中间

那么其他 Provider 呢？OpenAI 自家的 Responses API 如今也提供了同构的 tool_search + defer_loading 协议（我们放到本节末尾再讲），但广大「OpenAI 兼容」生态——vLLM、OpenRouter、各家自建兼容层等通常只能二选一：发送 tools → 全部进入模型上下文，或者不发送 tools → Provider 不承认对应的原生调用。它们缺少 defer_loading 和 tool_reference 这种 Provider 级协议。因此我们如果自己动手动态增加工具，就会改变早期前缀并破坏缓存。

于是就有了下面两条客户端自救路线。

2.但是服务端不支持怎么办？一个折中的压缩选项：stub 注册工具#

这是我之前实现过的一个方案，核心思路是：既然 tools 数组一个字都不能动，那就在「注册全部工具」的前提下，把每一个工具的契约在未被需要之前压缩到极限。

具体做法可以分为两部分。第一部分是把每个真实工具都注册成一个 stub：保留真实工具名，描述尽量压缩，参数契约则换成一个宽松的万能外壳；第二部分是在工具列表里常驻一个普通的 load_tool_schemas 工具，由我们的客户端实现。Stub 大概长这样：

1
{
2
  "name": "learning_create_cards",
3
  "description": "从学习笔记创建记忆卡片。调用前必须先调用 load_tool_schemas 获取完整参数契约。",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "arguments": { "type": "object", "additionalProperties": true }
8
    }
9
  }
10
}

完整的调用流程是：

1
模型认为自己需要制卡能力
2
    ↓
3
1. 模型调用 load_tool_schemas({ "tools": ["learning_create_cards"] })
4
2. 客户端返回完整 JSON Schema（作为普通 tool_result 文本）
5
3. 模型按照刚拿到的 schema 调用 learning_create_cards 这个 stub

注意第 2 步的完整契约是以消息的形式回来的，追加在对话尾部，不碰任何前缀，因此可以复用之前的全部缓存。我们可以计算一下这种方案的 tokens 消耗：第一节中我们按照 400 token/工具估过 200 个工具的上下文消耗大概为 80k；换成 stub 之后，每个工具大概只剩名字、一句话描述和宽松契约，约 60-80tokens，同样的 200 个工具的上下文消耗大概可以被压缩到 15k 左右，降低了 80%的上下文消耗。

但这个方案并没有让问题消失，stub 的数量依然是 $O(N)$ 的，并没有实现真正的渐进式披露加载；而且每个 stub 都常驻在模型的上下文中，对于模型注意力的消耗也仍然是实打实的。另外它本质上是一种「半原生」方案：Provider 的语法约束还在，但约束的是 stub 那个宽松外壳，真实参数的合法性需要完全靠客户端自己约束。

3.进一步简化：客户端实现 tool search，注册更宽松的工具#

当然，我们可以进一步简化。

让我们重新审视一下目前工具调用的两个基本前提：

1. 工具在 Provider 注册；
2. 模型可以正确遵循工具契约。

第一条其实可以被收窄到极限——注册的可以只有一个工具；而第二条，随着当前旗舰模型指令遵循能力的提升，「把契约以文本形式交给模型，它就能照着填参数」已经是一项相当可靠的能力。因此我们完全可以定义一个通用的、全能的 invoke_tool，把所有真实工具都藏到其背后：

1
{
2
  "name": "invoke_tool",
3
  "description": "执行工具目录中的工具。请先用 search_tools 找到目标工具，再按返回的契约填写 arguments。",
4
  "parameters": {
5
    "type": "object",
6
    "properties": {
7
      "tool_name": { "type": "string" },
8
      "arguments": { "type": "object", "additionalProperties": true }
9
    },
10
    "required": ["tool_name", "arguments"]
11
  }
12
}

tools 数组从此恒定，里面只有两个工具：search_tools 和 invoke_tool。一次完整的发现与调用是这样的：

1
1. 模型 → search_tools({ "query": "create flashcards from study notes" })
2
2. 客户端 → 返回目录条目（工具名 + 一行描述，不含完整 schema）
3
3. 模型 → invoke_tool({
4
     "tool_name": "learning_create_cards",
5
     "arguments": { "notes": "...", "mode": "qa" }
6
   })
7
4. 客户端 → 按 tool_name 取出真实 schema 校验 → 执行 → 回传结果
8
   （校验失败 → 回结构化错误 → agent 修正重试）

对比一下之前 2.2 节的方案：

1
之前：
2
N 个具体 Stub + load_tool_schemas
3

4
现在：
5
1 个 invoke_tool + search_tools

初始上下文占用从 $O(N)$ 直接变成了 $O(1)$——不管工具目录里躺着 100 个还是 10,000 个工具，模型看到的永远只有初始的两个工具（大概只有几百 tokens 的占用）。工具目录本身可以是一个普通的本地索引、一张数据库表、甚至一个 embedding 检索服务，我们在本地可以实现非常自由的检索。

那么，这个方案的代价又是什么呢？

代价是我们无法复刻 Anthropic 的一个核心能力：Provider 只知道 invoke_tool 的外层 schema，不知道 learning_create_cards 的内层 schema。也就是说，在 Provider 侧是无法约束校验这个工具调用的参数是否「真的」格式正确的——外层有语法约束，但里面的 arguments 则是一个不设防的黑盒。真实校验必须由我们的客户端完整承担，一旦失败，就返回结构化校验错误让 agent 修正。除此之外还有一些隐性成本：真实参数变成了「JSON 里的 JSON」，转义和嵌套多了一层；而且这条路线对模型本身的指令遵循能力有门槛，太弱的模型会在第 3 步频繁出错。

公平起见，补偿也是有的：因为所有具体调用都收敛到了同一个入口，校验、授权、审计、限流这些横切关注点反而只需要在 Gateway 一处实现——这在多 User/Agent 场景里简直是意外之喜。

因此，没有 Provider 原生配合时，以下三个目标无法同时满足：

1. 初始上下文不包含 N 个具体工具或 Stub；
2. 工具列表始终稳定，不破坏早期 Prompt Cache；
3. 每个具体工具仍以独立原生工具和严格 schema 被 Provider 调用、约束。

三者只能取二：

4.Moonshot 的按需加载工具机制#

Moonshot 在 Kimi K3 的 API 里提供了一个叫「动态加载工具」的机制。月暗的思路是：工具声明不一定要待在请求开头的 tools 字段里，它可以是一条消息。

具体做法是：在 messages 中插入一条 role 为 system、携带 tools 字段的消息。声明格式与请求顶层 tools 完全一致，且必须提供工具的完整信息（name、description、parameters）：

1
{
2
  "messages": [
3
    {
4
      "role": "system",
5
      "content": "You are Kimi, an AI assistant..."
6
    },
7
    {
8
      "role": "user",
9
      "content": "Calculate fuel consumption."
10
    },
11
    {
12
      "role": "system",
13
      "tools": [
14
        {
15
          "type": "function",
16
          "function": {
17
            "name": "Calculator",
18
            "description": "计算器，只支持单个算术表达式的求值",
19
            "parameters": {
20
              "type": "object",
21
              "properties": {
22
                "expr": {
23
                  "type": "string",
24
                  "description": "算术表达式，支持四则运算、指数运算、对数函数、三角函数，使用 javascript 语法"
25
                }
26
              },
27
              "required": ["expr"]
28
            }
29
          }
30
        }
31
      ]
32
    }
33
  ]
34
}

这个设计有几个关键的语义：

• 携带 tools 的 system 消息与普通消息地位相同：它出现在 messages 的哪个位置，工具就从哪个位置开始对模型可见；
• 动态加载的工具与顶层 tools 声明的全局工具并存，模型可以同时看到两类；
• 注入的声明必须是完整定义，不能只传个工具名；
• 这条 system 消息不能再带 content 字段，否则请求会以 400 报错。

那缓存呢？官方给的原则有四条：

换句话说：追加，不要插入；注入了就别删。 工具声明被当成普通对话内容的一部分往后追加，前缀纹丝不动，就和 Skills 的加载路径一模一样。基于这个思路，官方顺手给出了 tool search 的参考实现（API 层面并没有内置的搜索接口）：

1. 顶层 tools 里只声明一个自己实现的 search_tools；
2. 在 system prompt 里告诉模型有哪些可搜索的工具目录/领域关键词；
3. 模型需要工具时先调 search_tools，后端按关键词返回匹配的工具名和简介；
4. 应用把命中工具的完整声明通过一条带 tools 的 system 消息追加到末尾；
5. 模型在后续生成中直接原生调用这些新加载的工具。

我们可以将Kimi 的按需加载工具方案可以视为一种 Provider 原生支持的、协议设计更轻量、使用更自由的选择。它在协议层面上不需要任何的额外概念，不需要提供  defer_loading、tool_reference 等新字段，声明格式与顶层 tools 完全一致；在位置上，工具在 messages 的哪个位置注入，就从哪个位置开始对模型可见，直觉且可控，且天然的对缓存友好；在自由度更高的基础上还依然享有 Provider 侧的原生约束，不会像 invoke_tool 那样把参数黑盒化，十分之优雅，令人眼馋。

相关文档与延伸阅读#

• Anthropic：Tool Search Tool Anthropic 官方的工具搜索与延迟加载方案，介绍了 defer_loading、BM25/Regex 搜索以及工具发现后的调用流程。
• OpenAI：Tool Search OpenAI Responses API 的工具搜索机制，支持通过 defer_loading 按需加载 Function、Namespace 和 MCP 工具。
• Moonshot AI：动态加载工具 Kimi API 的动态工具加载协议，允许通过 messages 中的 System Message，在对话过程中追加完整工具声明。
• Anthropic：Tool Reference Anthropic 工具协议的完整字段说明，包括 defer_loading、tool_reference、Strict Tool Use 等机制。
• Anthropic：Tool Use with Prompt Caching 介绍工具定义与 Prompt Cache 的关系，以及修改、追加工具时可能造成的缓存失效问题。
• 延伸阅读：上下文稀缺、RAG、Memory 与 Skills 关于上下文稀缺性，以及 RAG、Memory 和 Skills 等上下文管理机制的进一步讨论。