工具调用

工具调用让模型生成结构化的函数参数，由你的应用执行真实操作，再把结果返回给模型。模型不会替你执行函数；权限校验、参数验证和副作用控制都由你的代码负责。

选择协议

场景	推荐协议
需要兼容大量现有 SDK 与客户端	Chat Completions
新的 OpenAI Agent 工作流	Responses API
Claude 原生工具使用	Anthropic Messages
Gemini 原生 Function Calling	Gemini-compatible API

不同协议的工具定义和事件格式不同，不能直接复制请求体。

Chat Completions 示例

1. 声明工具

curl https://getrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "查询上海今天的天气"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "查询指定城市的天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"],
            "additionalProperties": false
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

2. 验证并执行

读取 choices[0].message.tool_calls，解析 function.arguments 后：

使用 JSON Schema 或等效方式再次校验参数；
检查当前用户是否有权限执行；
设置超时和资源限制；
对写操作要求显式确认；
记录 tool_call_id、耗时和结果状态。

3. 返回工具结果

将原始 assistant 消息和工具结果一并放入下一次请求：

{
  "role": "tool",
  "tool_call_id": "CALL_ID",
  "content": "{\"temperature\":28,\"condition\":\"sunny\"}"
}

Responses API

Responses 的工具定义将函数名称、说明和参数直接放在工具对象中，返回事件也不同：

{
  "model": "MODEL_ID",
  "input": "查询上海今天的天气",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "查询指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

执行后使用 function_call_output 和返回的 call_id 继续会话。具体字段请查看 Responses 接口参考。

可靠性建议

工具名称保持短、稳定且语义明确。
描述“何时使用”，不要只重复工具名称。
参数 Schema 尽量收紧，拒绝未知字段。
对同一 tool_call_id 做幂等处理，避免重试产生重复副作用。
限制单轮工具数量、执行时长和输出长度。
将工具错误作为结构化结果返回，不要伪装成成功。
普通文本成功不代表 Tool Calling 可用；上线前单独验证模型、协议和客户端组合。

常见问题

现象	检查项
模型只返回文字	模型能力、工具描述、`tool_choice`
参数不是合法 JSON	模型能力、Schema 复杂度、是否启用严格模式
工具被重复执行	客户端重试和幂等控制
第三方 Agent 无法识别结果	协议事件格式与工具版本兼容性

#工具调用

#选择协议

#Chat Completions 示例

#1. 声明工具

#2. 验证并执行

#3. 返回工具结果

#Responses API

#可靠性建议

#常见问题