Configure your model to work with external tools and use the results in its response.

Tool calling (also known as function calling) refers to a model’s ability to interact with external tools outside itself—such as querying a database or calling an external API. You provide tool definitions in your request. The model does not run your code. The model returns a structured tool call request. Your application decides whether and how to execute this request, and then returns the results to the model to be integrated into a final response. Support is per-model—check the Tool Calling column under Available Models.

How tool calling works

A tool calling interaction consists of four main steps:

Define your tools: Use the tools request parameter to tell the model which functions your application can run, what each function does, and what arguments it accepts. You must also implement the corresponding functions in your application.
Send the request: Include the tool definitions in a Chat Completions request. Use the tool_choice parameter to control tool selection.
Run the requested function: If the model returns a tool call, validate its arguments and execute the corresponding function in your application.
Return the result: Append the assistant’s tool-call message to the conversation, followed by the tool result associated with the matching tool_call_id. Send the updated conversation back to the model so it can compose an answer.

The model may answer directly without calling a tool, or request one or more tool calls, depending on the prompt, model capabilities, and tool_choice setting. Tool-calling behavior and support varies by model. See the annotated example below, which shows a complete tool calling interaction.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api-cdn.deploy.com/api/v1",
    api_key="DEPLOY_API_KEY",
)

model = "DEPLOY_MODEL_ID"

# Define the available tools in a JSON schema
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The city to get weather for",
                    }
                },
                "required": ["city"],
                "additionalProperties": False,
            },
        },
    }
]

# Define and implement the function in your application
def get_weather(city):
    # Replace this example with a real weather API call
    return {
        "city": city,
        "temperature_f": 60,
        "conditions": "Cloudy",
    }

# Send the user's message and tool definitions to the model
messages = [
    {
        "role": "user",
        "content": "What's the weather in San Francisco?",
    }
]

response = client.chat.completions.create(
    model=model,
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

assistant_message = response.choices[0].message

# Check whether the model requested any tool calls
if assistant_message.tool_calls:
    # Preserve the assistant's tool-call message in the conversation
    messages.append(assistant_message)

    # Execute each requested tool and append its result
    for tool_call in assistant_message.tool_calls:
        function_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)

        # Only execute functions explicitly allowed by your application
        if function_name == "get_weather":
            result = get_weather(**arguments)
        else:
            raise ValueError(f"Unknown tool: {function_name}")

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result),
        })

    # Send the tool results back to the model
    # The model can now generate a final answer using those results
    response = client.chat.completions.create(
        model=model,
        messages=messages,
        tools=tools,
        tool_choice="auto",
    )

    # Print the model's latest response
    # For simplicity, this example handles one tool-call round
    print(response.choices[0].message.content)

else:
    # The model may answer directly without calling a tool
    print(assistant_message.content)

Streaming

When streaming is enabled, tool-call information may arrive across multiple chunks. Accumulate the relevant deltas off choices[0].delta.tool_calls in the stream until the tool call and its arguments are complete before parsing and executing it.

Get Started

Chat Completions

Large Language Models

Security & Compliance

Tool Calling

How tool calling works

Streaming

​How tool calling works

​Streaming

How tool calling works

Streaming