协议机制

2.1tool 定义：name / description / input_schema

一个工具定义就是 name + description + 一份 JSON Schema 参数表，提前声明给模型。

工具调用的起点不是代码，而是一段声明。在发起请求时，caller 把可用工具列表放进 tools 字段，每个工具至少包含三件事：name（模型用来指名调用）、description（模型用来判断「这工具是干什么的、什么时候该用」）、参数表（模型用来知道每个参数叫什么、是什么类型、哪些必填）。

{
  "name": "get_weather",
  "description": "查询指定城市的当前天气。当用户询问实时天气时调用。",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市名，如 San Francisco"
      }
    },
    "required": ["location"]
  }
}

这是 Anthropic 风格的写法。input_schema 内部就是标准 JSON Schema：顶层是一个 object，properties 列出每个参数，required 标出必填项。模型读到它，就知道「调 get_weather 时必须给一个叫 location 的字符串」。

2.2一次往返的报文：tool_use + stop_reason + tool_result

模型回一个 tool_use 块并停机，caller 执行后用一条 user 消息把 tool_result 送回去。

续用 01 章的天气例子，看 Anthropic Messages API 里一次完整往返的报文形状。整个循环是四拍：

• caller 发请求（带上 tools 定义）；
• 模型回一条 assistant 消息，stop_reason 为 "tool_use"，且 content 里含一个 tool_use 块；
• caller 在自己的程序里执行那个工具；
• caller 发一条 role:"user" 消息，content 里装一个 tool_result 块——模型据此继续。

// ② 模型这一轮的回复（assistant）
{
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01A",
      "name": "get_weather",
      "input": { "location": "San Francisco" }
    }
  ]
}

// ③ 你的程序执行后，把结果作为一条 user 消息发回
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A",
      "content": "15°C, 多云",
      "is_error": false
    }
  ]
}

2.3Anthropic ↔ OpenAI 术语对照

同一套机制，两家的字段名和数据形状不同。读别人的代码、跨厂商迁移时，这张表是高频参照。

2.4tool_choice：让不让、让不让得了哪个

tool_choice 控制四种姿态：自由决定、必须调某个、钉死某个、完全禁止。

tool_choice 决定模型在这一轮对工具的姿态。四种语义（括号内为两家的命名）：

• auto（默认）——模型自行决定调不调、调哪个。
• any（Anthropic）/ required（OpenAI）——必须调某个工具，但不指定是哪个，由模型从工具列表里挑。
• 指定某工具——钉死调用哪个：Anthropic 用 {"type":"tool","name":"x"}，OpenAI 用 {"type":"function","function":{"name":"x"}}。
• none——禁止调用任何工具，模型只能直接回文本。

2.5并行工具调用

一个回合可以请求多件事；两家的结果回填形状不同，但都靠 id 对应。

一个 assistant turn 可以一次带多个 tool_use 块（OpenAI 对应 tool_calls 数组里多个元素）。回填方式两家不同：

• Anthropic：把多个 tool_result 放进同一条 user 消息的 content 数组里。
• OpenAI：每个 tool_call_id 对应一条独立的 role:"tool" 消息。

不论哪种形状，结果与请求的对应关系都靠 id（tool_use_id / tool_call_id）维系。机制上，并行只是「一个回合里请求多件事」，执行仍由 harness 负责——彼此独立的调用可以并发跑，从而省墙钟时间（03 章会讲并行带来的隐患，例如互相依赖或写同一资源）。

2.6流式：参数是一点点拼出来的

流式下工具参数逐 chunk 到达，中途是残缺 JSON，block 结束才完整。

开启流式后，工具参数不是一次性给全，而是逐 chunk 到达：Anthropic 通过 input_json_delta 事件吐出 partial_json 片段；OpenAI 通过分块的 delta.tool_calls[].function.arguments 累加。在到达过程中，手里的内容是不完整、甚至不合法的 JSON——只有当这个工具调用 block 结束时，所有片段拼起来才构成一个完整可解析的对象。

2.7深一层：模型到底怎么「生成」一个调用

工具调用就是普通生成的 token；JSON 合法性靠事后重试或约束解码，不是天生的。

前六节都在讲「报文长什么样」。这一节下沉一层，讲模型究竟怎么把那个 tool_use 块生成出来——这是读官方文档读不到、却决定了你怎么排错的那层。

一个工具调用就是普通生成的 token

模型并没有一个「调用工具」的特殊能力开关。harness 把每个工具的 {name, description, input_schema} 序列化进 context；模型经过后训练（在成千上万条工具调用轨迹上微调），学会在该调用时输出一段被 tokenizer 认得的、包着特殊 token 的结构化片段；harness 再按模式匹配这些特殊 token，从中解析出 name 与那段 JSON 参数，组装成 API 里你看到的 tool_use 块。整段过程，模型做的事和「写一句话」没有本质区别——都是在预测下一个 token。

JSON 合法性不是天生的

既然只是 token 预测，纯生成完全会吐出非法 JSON（少个引号、括号不配对、字段名拼错）。合法性靠工程手段补，主流是两条路：

• ① 事后解析重试——拿到输出就尝试 parse，失败了就把错误信息塞回去、重新提示模型再生成一次。简单、不改采样过程，但有失败重试的额外开销与延迟。
• ② 约束解码（constrained decoding）——把 JSON Schema 提前编译成一套语法 / 状态机，在模型和采样器之间插一个 logit 处理器：每一步只允许「符合语法的下一个 token」，把所有不符合的 token 的 logit 强行设成 −∞。于是采样器只会采到 schema 合法的 token。模型权重一字不改，被改的只是采样时每一步的候选集合。

关键代价与边界

约束解码看着像银弹，但它有明确的边界：只保证语法，不保证语义。schema 说 location 是字符串，约束解码能保证模型确实吐出一个字符串、整体 JSON 也合法；但模型把用户问的 "San Francisco" 填成 "New York"，它一点办法没有——参数形状对、值却错（valid but wrong）是这条路绕不开的盲区。代价上还有两笔：每生成一个 token 都要算一次 mask 的运行时开销，以及把 schema 编译成语法 / 状态机的一次性延迟。