API GuidesResponses API

Tool Calling

Function calling and tool integration with the Responses API Beta
Beta API

This API is in beta stage and may have breaking changes.

The Responses API Beta supports comprehensive tool calling capabilities, allowing models to call functions, execute tools in parallel, and handle complex multi-step workflows.

Basic Tool Definition

Define tools using the OpenAI function calling format:

1const weatherTool = {
2  type: 'function' as const,
3  name: 'get_weather',
4  description: 'Get the current weather in a location',
5  strict: null,
6  parameters: {
7    type: 'object',
8    properties: {
9      location: {
10        type: 'string',
11        description: 'The city and state, e.g. San Francisco, CA',
12      },
13      unit: {
14        type: 'string',
15        enum: ['celsius', 'fahrenheit'],
16      },
17    },
18    required: ['location'],
19  },
20};
21
22const response = await fetch('https://openrouter.ai/api/v1/responses', {
23  method: 'POST',
24  headers: {
25    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
26    'Content-Type': 'application/json',
27  },
28  body: JSON.stringify({
29    model: 'openai/o4-mini',
30    input: [
31      {
32        type: 'message',
33        role: 'user',
34        content: [
35          {
36            type: 'input_text',
37            text: 'What is the weather in San Francisco?',
38          },
39        ],
40      },
41    ],
42    tools: [weatherTool],
43    tool_choice: 'auto',
44    max_output_tokens: 9000,
45  }),
46});
47
48const result = await response.json();
49console.log(result);

Tool Choice Options

Control when and how tools are called:

Tool ChoiceDescription
autoModel decides whether to call tools
noneModel will not call any tools
{type: 'function', name: 'tool_name'}Force specific tool call

Force Specific Tool

1const response = await fetch('https://openrouter.ai/api/v1/responses', {
2  method: 'POST',
3  headers: {
4    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    model: 'openai/o4-mini',
9    input: [
10      {
11        type: 'message',
12        role: 'user',
13        content: [
14          {
15            type: 'input_text',
16            text: 'Hello, how are you?',
17          },
18        ],
19      },
20    ],
21    tools: [weatherTool],
22    tool_choice: { type: 'function', name: 'get_weather' },
23    max_output_tokens: 9000,
24  }),
25});

Disable Tool Calling

1const response = await fetch('https://openrouter.ai/api/v1/responses', {
2  method: 'POST',
3  headers: {
4    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    model: 'openai/o4-mini',
9    input: [
10      {
11        type: 'message',
12        role: 'user',
13        content: [
14          {
15            type: 'input_text',
16            text: 'What is the weather in Paris?',
17          },
18        ],
19      },
20    ],
21    tools: [weatherTool],
22    tool_choice: 'none',
23    max_output_tokens: 9000,
24  }),
25});

Multiple Tools

Define multiple tools for complex workflows:

1const calculatorTool = {
2  type: 'function' as const,
3  name: 'calculate',
4  description: 'Perform mathematical calculations',
5  strict: null,
6  parameters: {
7    type: 'object',
8    properties: {
9      expression: {
10        type: 'string',
11        description: 'The mathematical expression to evaluate',
12      },
13    },
14    required: ['expression'],
15  },
16};
17
18const response = await fetch('https://openrouter.ai/api/v1/responses', {
19  method: 'POST',
20  headers: {
21    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
22    'Content-Type': 'application/json',
23  },
24  body: JSON.stringify({
25    model: 'openai/o4-mini',
26    input: [
27      {
28        type: 'message',
29        role: 'user',
30        content: [
31          {
32            type: 'input_text',
33            text: 'What is 25 * 4?',
34          },
35        ],
36      },
37    ],
38    tools: [weatherTool, calculatorTool],
39    tool_choice: 'auto',
40    max_output_tokens: 9000,
41  }),
42});

Parallel Tool Calls

The API supports parallel execution of multiple tools:

1const response = await fetch('https://openrouter.ai/api/v1/responses', {
2  method: 'POST',
3  headers: {
4    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    model: 'openai/o4-mini',
9    input: [
10      {
11        type: 'message',
12        role: 'user',
13        content: [
14          {
15            type: 'input_text',
16            text: 'Calculate 10*5 and also tell me the weather in Miami',
17          },
18        ],
19      },
20    ],
21    tools: [weatherTool, calculatorTool],
22    tool_choice: 'auto',
23    max_output_tokens: 9000,
24  }),
25});
26
27const result = await response.json();
28console.log(result);

Tool Call Response

When tools are called, the response includes function call information:

1{
2  "id": "resp_1234567890",
3  "object": "response",
4  "created_at": 1234567890,
5  "model": "openai/o4-mini",
6  "output": [
7    {
8      "type": "function_call",
9      "id": "fc_abc123",
10      "call_id": "call_xyz789",
11      "name": "get_weather",
12      "arguments": "{\"location\":\"San Francisco, CA\"}"
13    }
14  ],
15  "usage": {
16    "input_tokens": 45,
17    "output_tokens": 25,
18    "total_tokens": 70
19  },
20  "status": "completed"
21}

Tool Responses in Conversation

Include tool responses in follow-up requests:

1const response = await fetch('https://openrouter.ai/api/v1/responses', {
2  method: 'POST',
3  headers: {
4    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    model: 'openai/o4-mini',
9    input: [
10      {
11        type: 'message',
12        role: 'user',
13        content: [
14          {
15            type: 'input_text',
16            text: 'What is the weather in Boston?',
17          },
18        ],
19      },
20      {
21        type: 'function_call',
22        id: 'fc_1',
23        call_id: 'call_123',
24        name: 'get_weather',
25        arguments: JSON.stringify({ location: 'Boston, MA' }),
26      },
27      {
28        type: 'function_call_output',
29        id: 'fc_output_1',
30        call_id: 'call_123',
31        output: JSON.stringify({ temperature: '72°F', condition: 'Sunny' }),
32      },
33      {
34        type: 'message',
35        role: 'assistant',
36        id: 'msg_abc123',
37        status: 'completed',
38        content: [
39          {
40            type: 'output_text',
41            text: 'The weather in Boston is currently 72°F and sunny. This looks like perfect weather for a picnic!',
42            annotations: []
43          }
44        ]
45      },
46      {
47        type: 'message',
48        role: 'user',
49        content: [
50          {
51            type: 'input_text',
52            text: 'Is that good weather for a picnic?',
53          },
54        ],
55      },
56    ],
57    max_output_tokens: 9000,
58  }),
59});
Optional Field

The id field is optional for function_call_output objects. Only type, call_id, and output are required — call_id is what pairs the output with its originating function_call. The examples above include id for completeness, but you can safely omit it.

Multimodal tool outputs

function_call_output.output accepts either a string or an array of input content parts (input_text, input_image, input_file) — the same shape as user-message content. Use the array form to return images or files from a tool; the non-text parts are only forwarded to supported multimodal models.

1{
2  "type": "function_call_output",
3  "call_id": "call_123",
4  "output": [
5    {
6      "type": "input_text",
7      "text": "{\"results\":[{\"title\":\"Golden Gate Bridge\"}]}"
8    },
9    {
10      "type": "input_image",
11      "image_url": "https://example.com/image.jpg"
12    }
13  ]
14}

Streaming Tool Calls

Monitor tool calls in real-time with streaming:

1const response = await fetch('https://openrouter.ai/api/v1/responses', {
2  method: 'POST',
3  headers: {
4    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    model: 'openai/o4-mini',
9    input: [
10      {
11        type: 'message',
12        role: 'user',
13        content: [
14          {
15            type: 'input_text',
16            text: 'What is the weather like in Tokyo, Japan? Please check the weather.',
17          },
18        ],
19      },
20    ],
21    tools: [weatherTool],
22    tool_choice: 'auto',
23    stream: true,
24    max_output_tokens: 9000,
25  }),
26});
27
28const reader = response.body?.getReader();
29const decoder = new TextDecoder();
30
31while (true) {
32  const { done, value } = await reader.read();
33  if (done) break;
34
35  const chunk = decoder.decode(value);
36  const lines = chunk.split('\n');
37
38  for (const line of lines) {
39    if (line.startsWith('data: ')) {
40      const data = line.slice(6);
41      if (data === '[DONE]') return;
42
43      try {
44        const parsed = JSON.parse(data);
45        if (parsed.type === 'response.output_item.added' &&
46            parsed.item?.type === 'function_call') {
47          console.log('Function call:', parsed.item.name);
48        }
49        if (parsed.type === 'response.function_call_arguments.done') {
50          console.log('Arguments:', parsed.arguments);
51        }
52      } catch (e) {
53        // Skip invalid JSON
54      }
55    }
56  }
57}

Tool Validation

Ensure tool calls have proper structure:

1{
2  "type": "function_call",
3  "id": "fc_abc123",
4  "call_id": "call_xyz789",
5  "name": "get_weather",
6  "arguments": "{\"location\":\"Seattle, WA\"}"
7}

Required fields:

  • type: Always “function_call”
  • id: Unique identifier for the function call object
  • name: Function name matching tool definition
  • arguments: Valid JSON string with function parameters
  • call_id: Unique identifier for the call

Best Practices

  1. Clear descriptions: Provide detailed function descriptions and parameter explanations
  2. Proper schemas: Use valid JSON Schema for parameters
  3. Error handling: Handle cases where tools might not be called
  4. Parallel execution: Design tools to work independently when possible
  5. Conversation flow: Include tool responses in follow-up requests for context

Next Steps