Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

AI agents are programs that use a language model to decide what to do next, take actions through tools, and loop until they complete a goal — rather than producing a single response and stopping. The model acts as the reasoning engine: you give it a set of instructions, a set of tools, and the current state of the conversation, and it decides which tool to call, in what order, and when the task is done. This is a fundamentally different pattern from one-shot completions, and it unlocks a much wider class of problems.

​
Key components of an agent

Every agent is built from three primitives:
  • Model — the language model that reasons and decides what to do next (e.g. gpt-4o)
  • Instructions — a system prompt that defines the agent’s role, constraints, and workflow
  • Tools — functions, APIs, or other agents the model can call to take actions in the world
When the model determines it needs information or needs to do something, it emits a tool call. Your code executes the tool and returns the result. The model then continues reasoning until it reaches a final answer or the task is complete.

​
A simple agent example

The following example shows a minimal agent loop using the Chat Completions API. The agent has access to a get_weather tool and will call it as needed to answer the user’s question. 
from openai import OpenAI
import json

client = OpenAI()

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City and state, e.g. 'San Francisco, CA'"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

def get_weather(location: str) -> str:
    # Replace with a real weather API call
    return f"Sunny, 72°F in {location}"

messages = [{"role": "user", "content": "What's the weather in Austin, TX?"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
    )
    choice = response.choices[0]
    messages.append(choice.message)

    # If no tool calls, we're done
    if not choice.message.tool_calls:
        print(choice.message.content)
        break

    # Execute each requested tool call
    for tool_call in choice.message.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = get_weather(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": result,
        })
The loop continues until the model returns a message with no tool calls. This is how you know the agent considers its task complete.

​
Routines and instructions

A routine is a set of natural-language steps combined with the tools needed to carry them out. Think of it as the agent’s operating procedure. A well-written routine makes the agent predictable and controllable. 
system_prompt = (
    "You are a customer support agent for ACME Inc. "
    "Follow this routine with every user:\n"
    "1. Ask clarifying questions to understand the problem.\n"
    "2. Propose a fix.\n"
    "3. Only if the user is unsatisfied, offer a refund.\n"
    "4. If they accept, look up their order ID and process the refund."
)
Good instructions specify: the agent’s persona, the exact workflow steps, what the agent should and should not do, and how to handle ambiguous or edge cases.

​
Single-agent vs. multi-agent patterns

Single agent

One model with a set of tools handles the entire task. Best for focused workflows with a clear scope — customer support, code review, document summarization.

Multi-agent

Multiple specialized agents collaborate. A triage agent routes tasks to specialists, or agents run in parallel to reduce latency. Best for complex, multi-domain workflows.

​
When to use a single agent

Use a single agent when:
  • The task fits inside a single context window
  • The tools are cohesive and few in number
  • You want simplicity, predictability, and easy debugging

​
When to use multiple agents

Use a multi-agent setup when:
  • Different parts of the task require different expertise or prompting strategies
  • You want to run independent subtasks in parallel to reduce latency
  • You need one agent to check the work of another (verification loops)
  • The workflow has clear handoff points between phases

​
Handoffs between agents

A handoff is when one agent passes control — along with any relevant context — to another agent. The receiving agent picks up from where the first left off. This is the core primitive for building multi-agent systems. 
# Triage agent decides which specialist to hand off to
triage_instructions = (
    "You are a triage agent. Determine whether the user has a billing issue "
    "or a technical issue, then hand off to the appropriate specialist agent."
)

# Specialist agents
billing_instructions = "You handle billing disputes and refunds."
technical_instructions = "You help users debug integration errors."
The OpenAI Agents SDK provides a built-in handoff mechanism that handles context passing automatically, so you don’t have to manage this state manually.

​
When to use agents at all

Agents are most valuable when the solution path is not known upfront and requires dynamic decision-making. If you can write a deterministic program that solves the problem, do that instead — it will be faster, cheaper, and more reliable. Use agents when:
  • The task requires adapting to unpredictable inputs
  • Multiple tools may be needed in an order that depends on runtime conditions
  • The task is too complex for a single-step prompt
Start with the simplest possible setup — one model, a few tools, a clear system prompt. Add agents and complexity only when you have a concrete reason.

​
Next steps

OpenAI Agents SDK

Use the official SDK to build, run, and evaluate agents with less boilerplate.

Function calling

Learn how to define tools and handle tool calls in the Chat Completions API.

Build docs developers (and LLMs) love

Get started for freeTalk to us