Claude Code 网关工具调用协议

目标

根据本 skill，实现大模型网关中的工具调用兼容。服务端需要理解 Claude Code 发来的 tools schema，并在模型需要工具时返回 Anthropic tool_use block；客户端下一轮会回传 tool_result。

详细字段见 references/tool-schema-wire-format.md。

请求中的 tools

POST /v1/messages 可能包含：

{
  "tools": [
    {
      "name": "Bash",
      "description": "...",
      "input_schema": { "type": "object", "properties": {}, "required": [] }
    }
  ],
  "tool_choice": { "type": "auto" }
}

网关要求：

• 保留工具 name，响应中的 tool_use.name 必须完全匹配。
• input_schema 是 JSON Schema；你可以传给上游模型，也可以转换为上游工具格式。
• 容忍 strict、eager_input_streaming、defer_loading、cache_control 等扩展字段。
• MCP 工具名形如 mcp__server_name__tool_name，不要拆错。

返回 tool_use

流式：

content_block_start: {"type":"tool_use","id":"toolu_1","name":"Bash","input":{}}
content_block_delta: {"type":"input_json_delta","partial_json":"{\"command\""}
content_block_delta: {"type":"input_json_delta","partial_json":":\"ls\"}"}
content_block_stop
message_delta: {"stop_reason":"tool_use"}
message_stop

非流式：

{
  "content": [
    { "type": "tool_use", "id": "toolu_1", "name": "Bash", "input": { "command": "ls" } }
  ],
  "stop_reason": "tool_use"
}

接收 tool_result

Claude Code 下一轮会发送：

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_1", "content": "file list", "is_error": false }
  ]
}

网关要把它作为上一轮工具执行结果传给上游模型。tool_use_id 必须和之前返回的 tool_use.id 对上。

Deferred tools

如果工具带 defer_loading:true，表示服务端可以只把名称/描述暴露给模型，完整 schema 可能通过 ToolSearch 工作流补齐。外部网关最小实现可以忽略 defer，直接把工具当普通工具传给上游；但不要因为该字段报错。

兼容要求

• input_json_delta.partial_json 拼接后必须是 JSON object。
• 如果上游模型返回 OpenAI function call，网关要转换成 Anthropic tool_use。
• 如果上游工具调用参数不是合法 JSON，返回 502 或合成文本错误，不要输出畸形 input_json_delta。
• 不要执行工具；Claude Code 客户端负责本地工具执行。网关只负责让模型请求工具，并在下一轮读取结果。