> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auriko.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Calling

> Call functions using the Response API's input/output item format

Tool definitions use a flat schema (`{type, name, parameters}`) and tool results are `function_call_output` input items with a `call_id` and `output` string.

## Prerequisites

* An [Auriko API key](https://auriko.ai/signup?redirectTo=%2Fdashboard%3Ftab%3Dapi-keys)
* Python 3.10+ with the OpenAI SDK (`pip install openai`) or the Auriko SDK (`pip install auriko`)
  * OR Node.js 18+ with the OpenAI SDK (`npm install openai`) or `@auriko/sdk` (`npm install @auriko/sdk`)

## Define tools

Define a tool with the flat schema format:

<CodeGroup>
  ```python Python OpenAI theme={null}
  tools = [
      {
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }
  ]
  ```

  ```typescript TypeScript OpenAI theme={null}
  const tools = [
      {
          type: "function" as const,
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      },
  ];
  ```

  ```python Python Auriko theme={null}
  tools = [
      {
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }
  ]
  ```

  ```typescript TypeScript Auriko theme={null}
  const tools = [
      {
          type: "function" as const,
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      },
  ];
  ```
</CodeGroup>

Chat Completions wraps these fields under a nested `function` key.

## Call tools

Send a request with tools and inspect the `function_call` output item:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }]
  )

  for item in response.output:
      if item.type == "function_call":
          print(f"Function: {item.name}")
          print(f"Arguments: {item.arguments}")
          print(f"Call ID: {item.call_id}")
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
  });

  for (const item of response.output) {
      if (item.type === "function_call") {
          console.log(`Function: ${item.name}`);
          console.log(`Arguments: ${item.arguments}`);
          console.log(`Call ID: ${item.call_id}`);
      }
  }
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }]
  )

  for item in response.output:
      if item.type == "function_call":
          print(f"Function: {item.name}")
          print(f"Arguments: {item.arguments}")
          print(f"Call ID: {item.call_id}")
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
  });

  for (const item of response.output) {
      if (item.type === "function_call") {
          console.log(`Function: ${item.name}`);
          console.log(`Arguments: ${item.arguments}`);
          console.log(`Call ID: ${item.call_id}`);
      }
  }
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "input": "What'\''s the weather in Tokyo?",
      "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }]
    }'
  ```
</CodeGroup>

## Submit tool results

Match the `call_id` from the function call output to link your result back to the original request:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  import json
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  tools = [{
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
      }
  }]

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=tools
  )

  tool_call = next(item for item in response.output if item.type == "function_call")

  final = client.responses.create(
      model="gpt-4o",
      input=[
          {"type": "message", "role": "user", "content": "What's the weather in Tokyo?"},
          {"type": "function_call", "name": tool_call.name, "call_id": tool_call.call_id, "arguments": tool_call.arguments},
          {"type": "function_call_output", "call_id": tool_call.call_id, "output": json.dumps({"temperature": "22°C", "condition": "Sunny"})}
      ],
      tools=tools
  )

  print(final.output_text)
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const tools = [{
      type: "function" as const,
      name: "get_weather",
      description: "Get current weather for a location",
      parameters: {
          type: "object",
          properties: {
              location: { type: "string", description: "City name" },
          },
          required: ["location"],
      },
  }];

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools,
  });

  const toolCall = response.output.find((item) => item.type === "function_call");

  const final = await client.responses.create({
      model: "gpt-4o",
      input: [
          { type: "message", role: "user", content: "What's the weather in Tokyo?" },
          { type: "function_call", name: toolCall.name, call_id: toolCall.call_id, arguments: toolCall.arguments },
          { type: "function_call_output", call_id: toolCall.call_id, output: JSON.stringify({ temperature: "22°C", condition: "Sunny" }) },
      ],
      tools,
  });

  console.log(final.output_text);
  ```

  ```python Python Auriko theme={null}
  import os
  import json
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  tools = [{
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
      }
  }]

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=tools
  )

  tool_call = next(item for item in response.output if item.type == "function_call")

  final = client.responses.create(
      model="gpt-4o",
      input=[
          {"type": "message", "role": "user", "content": "What's the weather in Tokyo?"},
          {"type": "function_call", "name": tool_call.name, "call_id": tool_call.call_id, "arguments": tool_call.arguments},
          {"type": "function_call_output", "call_id": tool_call.call_id, "output": json.dumps({"temperature": "22°C", "condition": "Sunny"})}
      ],
      tools=tools
  )

  print(final.output_text)
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const tools = [{
      type: "function" as const,
      name: "get_weather",
      description: "Get current weather for a location",
      parameters: {
          type: "object",
          properties: {
              location: { type: "string", description: "City name" },
          },
          required: ["location"],
      },
  }];

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools,
  });

  const toolCall = response.output.find((item) => item.type === "function_call");

  const final = await client.responses.create({
      model: "gpt-4o",
      input: [
          { type: "message", role: "user", content: "What's the weather in Tokyo?" },
          { type: "function_call", name: toolCall.name, call_id: toolCall.call_id, arguments: toolCall.arguments },
          { type: "function_call_output", call_id: toolCall.call_id, output: JSON.stringify({ temperature: "22°C", condition: "Sunny" }) },
      ],
      tools,
  });

  console.log(final.output_text);
  ```
</CodeGroup>

Submitting tool results requires state from a previous response. For single-request examples, see [Call tools](#call-tools).

## Use parallel tool calls

Set `parallel_tool_calls: true` to let the model call multiple functions in one response:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo and London?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }],
      parallel_tool_calls=True
  )

  for item in response.output:
      if item.type == "function_call":
          print(f"{item.name}({item.arguments})")
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo and London?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
      parallel_tool_calls: true,
  });

  for (const item of response.output) {
      if (item.type === "function_call") {
          console.log(`${item.name}(${item.arguments})`);
      }
  }
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo and London?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }],
      parallel_tool_calls=True
  )

  for item in response.output:
      if item.type == "function_call":
          print(f"{item.name}({item.arguments})")
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo and London?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
      parallel_tool_calls: true,
  });

  for (const item of response.output) {
      if (item.type === "function_call") {
          console.log(`${item.name}(${item.arguments})`);
      }
  }
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "input": "What'\''s the weather in Tokyo and London?",
      "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }],
      "parallel_tool_calls": true
    }'
  ```
</CodeGroup>

## Control tool choice

Set `tool_choice` to control when the model calls tools:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }],
      tool_choice="required"
  )

  print(response.output[0].type)
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
      tool_choice: "required",
  });

  console.log(response.output[0].type);
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }],
      tool_choice="required"
  )

  print(response.output[0].type)
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
      tool_choice: "required",
  });

  console.log(response.output[0].type);
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "input": "What'\''s the weather in Tokyo?",
      "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }],
      "tool_choice": "required"
    }'
  ```
</CodeGroup>

`"auto"` (default) lets the model decide. `"required"` forces a tool call. `"none"` prevents tool calls. `{"type": "function", "name": "get_weather"}` forces a specific function. See [Tool Calling guide](/guides/tool-calling) for provider-specific behavior.

## Stream tool calls

Stream function call arguments as they're generated:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  stream = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }],
      stream=True
  )

  for event in stream:
      if event.type == "response.function_call_arguments.delta":
          print(event.delta, end="", flush=True)
      elif event.type == "response.function_call_arguments.done":
          print(f"\nComplete: {event.arguments}")
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const stream = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
      stream: true,
  });

  for await (const event of stream) {
      if (event.type === "response.function_call_arguments.delta") {
          process.stdout.write(event.delta);
      } else if (event.type === "response.function_call_arguments.done") {
          console.log(`\nComplete: ${event.arguments}`);
      }
  }
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  stream = client.responses.create(
      model="gpt-4o",
      input="What's the weather in Tokyo?",
      tools=[{
          "type": "function",
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
              "type": "object",
              "properties": {
                  "location": {"type": "string", "description": "City name"}
              },
              "required": ["location"]
          }
      }],
      stream=True
  )

  for event in stream:
      if event.type == "response.function_call_arguments.delta":
          print(event.delta, end="", flush=True)
      elif event.type == "response.function_call_arguments.done":
          print(f"\nComplete: {event.arguments}")
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const stream = await client.responses.create({
      model: "gpt-4o",
      input: "What's the weather in Tokyo?",
      tools: [{
          type: "function",
          name: "get_weather",
          description: "Get current weather for a location",
          parameters: {
              type: "object",
              properties: {
                  location: { type: "string", description: "City name" },
              },
              required: ["location"],
          },
      }],
      stream: true,
  });

  for await (const event of stream) {
      if (event.type === "response.function_call_arguments.delta") {
          process.stdout.write(event.delta);
      } else if (event.type === "response.function_call_arguments.done") {
          console.log(`\nComplete: ${event.arguments}`);
      }
  }
  ```

  ```bash cURL theme={null}
  curl --no-buffer https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "input": "What'\''s the weather in Tokyo?",
      "tools": [{
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }],
      "stream": true
    }'
  ```
</CodeGroup>

The `.done` event includes the complete `arguments` string, so you don't need to reassemble delta chunks.