工具使用与函数调用

让模型调用您的函数——请求循环、两种格式，以及浪费 token 的常见错误。

工具使用让模型能够请求你运行一个函数，然后根据结果继续处理。这是所有编程智能体背后的机制。

交互循环

1. 你发送 messages 以及 tools ，用于描述可用的工具。
2. 模型回复一个 stop_reason: tool_use 以及一个 tool_use 块，其中指定工具名称及其参数。
3. 由你 执行它——网关绝不会运行你的代码。
4. 你将完整历史记录连同一个 tool_result 块一起发回。
5. 模型生成最终答案，或请求调用另一个工具。

定义工具（Messages 格式）

Copy{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Current weather for a city. Use when the user asks about weather.",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string", "description": "City name"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Paris?"}]
}

返回结果

Copy{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01ABC...",
    "content": "18C, light rain"
  }]
}

OpenAI 格式

该 /v1/chat/completions 端点使用 OpenAI 的 tools / tool_calls 格式，结果则以角色为以下值的消息返回 tool.

工具使用的成本

• 每轮都会重新发送定义。 即使对话尚未开始，二十个冗长的工具 schema 就可能占用大部分输入 token。
• 结果会成为上下文。 如果工具返回 200 行 JSON，这些内容会全部包含在下一次请求以及此后的每次请求中。
• 每次往返都是一次计费调用。 一个需要调用五个工具的任务至少需要六次请求。
• 限制工具输出的长度，并在返回前进行摘要。在大多数智能体循环中，将结果裁剪到模型实际需要的内容，是最能发挥作用的改进。