Responses API Beta 支持完整的工具调用能力，通过 tools 数组定义函数工具，tool_choice 参数控制调用策略（auto/none/强制指定）。工具调用响应包含 function_call 类型的 output item，多轮对话中需要将 function_call 和 function_call_output 一起包含在下一轮请求的 input 中。支持并行工具调用和 streaming 实时监控工具执行进度。

Beta API：该 API 处于 beta 阶段，可能存在破坏性变更。

Tool Choice 选项

通过 tool_choice 控制模型何时及如何调用工具：

Tool Choice	说明
auto	模型自行决定是否调用工具
none	模型不调用任何工具
{type: 'function', name: 'tool_name'}	强制调用指定工具

强制调用指定工具

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/o4-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [{ type: 'input_text', text: 'Hello, how are you?' }],
      },
    ],
    tools: [weatherTool],
    tool_choice: { type: 'function', name: 'get_weather' },
    max_output_tokens: 9000,
  }),
});

禁用工具调用

body: JSON.stringify({
  model: 'openai/o4-mini',
  input: [...],
  tools: [weatherTool],
  tool_choice: 'none',
  max_output_tokens: 9000,
}),

定义多个工具

const calculatorTool = {
  type: 'function',
  name: 'calculate',
  description: 'Perform mathematical calculations',
  strict: null,
  parameters: {
    type: 'object',
    properties: {
      expression: {
        type: 'string',
        description: 'The mathematical expression to evaluate',
      },
    },
    required: ['expression'],
  },
};

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/o4-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [{ type: 'input_text', text: 'What is 25 * 4?' }],
      },
    ],
    tools: [weatherTool, calculatorTool],
    tool_choice: 'auto',
    max_output_tokens: 9000,
  }),
});

工具调用响应格式

当模型调用工具时，响应的 output 数组包含 function_call 类型的 item：

{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1234567890,
  "model": "openai/o4-mini",
  "output": [
    {
      "type": "function_call",
      "id": "fc_abc123",
      "call_id": "call_xyz789",
      "name": "get_weather",
      "arguments": "{\"location\":\"San Francisco, CA\"}"
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 25,
    "total_tokens": 70
  },
  "status": "completed"
}

在对话中包含工具结果

在后续请求中需要将 function_call 和 function_call_output 一起包含在 input 中：

body: JSON.stringify({
  model: 'openai/o4-mini',
  input: [
    // 原始用户消息
    {
      type: 'message',
      role: 'user',
      content: [{ type: 'input_text', text: 'What is the weather in Boston?' }],
    },
    // 模型的工具调用（从上一轮响应中取）
    {
      type: 'function_call',
      id: 'fc_1',
      call_id: 'call_123',
      name: 'get_weather',
      arguments: JSON.stringify({ location: 'Boston, MA' }),
    },
    // 工具执行结果
    {
      type: 'function_call_output',
      id: 'fc_output_1',
      call_id: 'call_123',
      output: JSON.stringify({ temperature: '72°F', condition: 'Sunny' }),
    },
    // 模型的回复（包含 id 和 status）
    {
      type: 'message',
      role: 'assistant',
      id: 'msg_abc123',
      status: 'completed',
      content: [
        {
          type: 'output_text',
          text: 'The weather in Boston is currently 72°F and sunny.',
          annotations: []
        }
      ]
    },
    // 新的用户消息
    {
      type: 'message',
      role: 'user',
      content: [{ type: 'input_text', text: 'Is that good weather for a picnic?' }],
    },
  ],
  max_output_tokens: 9000,
}),

function_call_output 对象必须包含 id 字段。

Streaming 工具调用

在 streaming 模式下，通过监听以下事件类型实时跟踪工具调用进度：

• response.output_item.added（item.type === 'function_call'）— 检测到新的工具调用
• response.function_call_arguments.done — 工具调用参数传输完成

function_call 必填字段

字段	说明
type	固定为 "function_call"
id	function call 对象的唯一标识符
name	工具名称，必须与工具定义匹配
arguments	JSON 字符串，包含工具参数
call_id	调用的唯一标识符（与 function_call_output 的 call_id 对应）

最佳实践

1. 清晰的描述：为工具提供详细的功能描述和参数说明
2. 正确的 schema：使用合法的 JSON Schema 定义参数
3. 异常处理：处理工具未被调用或调用失败的情况
4. 并行设计：尽量设计可独立执行的工具，支持并行调用
5. 对话流程：在后续请求中完整包含工具调用历史

常见问题

Q: tool_choice: 'auto' 和不设置 tool_choice 有区别吗？

A: 效果相同，默认行为就是 auto——模型自行判断是否需要调用工具。

Q: 工具调用失败时如何通知模型？

A: 在 function_call_output 的 output 字段中返回错误信息（JSON 字符串），模型会根据错误内容调整回复。

Q: 并行工具调用如何处理多个结果？

A: 每个并行工具调用都有独立的 call_id，对应关系通过 function_call.call_id 和 function_call_output.call_id 匹配。在后续请求中按顺序包含所有 function_call 和对应的 function_call_output。