AI Engineer Roadmap All lessons Interactive Quiz GitHub

OpenAI Agents SDK

Intermediate · 11 min read · Updated · By Saurabh Pathak

In short: The OpenAI Agents SDK is a small Python library with three main ideas: an Agent (model plus instructions plus tools), a Runner that runs the agent loop, and handoffs between agents.

Play the interactive lesson: OpenAI Agents SDK: the Runner loopRead on GitHub
On this page
  1. Explain it like I'm new
  2. Watch it
  3. How it works
  4. Code example
  5. When to use it / when not to
  6. Common mistakes
  7. Recap
  8. Interview questions
  9. Go deeper

Level: Intermediate · Reading time: 11 min · Phase: 5 — Frameworks

Before you start: You should understand what a tool call is (Tool calling) and the agent loop (Agent loops).

Explain it like I'm new

Think of a help desk. A front-desk person answers simple questions and, for billing, passes you to a billing specialist. Each person has a role (instructions) and a set of things they can do (tools). The SDK models this directly.

It keeps the number of concepts low. You do not write the loop. The Runner calls the model, runs any tools it asks for, feeds results back, and stops when the model gives a final answer.

Words to know:

Watch it

OpenAI Agents SDK: the Runner loop: Agent plus Runner: the Runner repeats until there is a final output.
OpenAI Agents SDK: the Runner loop: Agent plus Runner: the Runner repeats until there is a final output.

It plays on a loop. Read the caption in the box, one step at a time. Want to go at your own pace? Step through it with Previous and Next.

How it works

  1. You define an agent with instructions and tools.
  2. The Runner sends the input and tool descriptions to the model.
  3. If the model asks for a tool, the Runner executes it and appends the result.
  4. If the model asks for a handoff, the Runner switches the active agent.
  5. Otherwise the reply is the final output.
flowchart TD
    U[user input] --> R{Runner loop}
    R --> M[model]
    M -->|tool call| T[run tool] --> R
    M -->|handoff| H[switch agent] --> R
    M -->|final text| O[output]

Mapping: this is the ReAct-style agent loop from Phase 4, packaged. Handoffs are the multi-agent routing pattern. Sessions are conversation memory.

Worked example

The scripted fake model in the code example below plays the role of the real LLM. I ran it with the input "What time is it in Paris?". Here is the message list at each turn.

  1. Start: messages = [user: "What time is it in Paris?"].
  2. Turn 1. The last message is from the user, so the fake model replies {"tool": "get_time", "args": {"city": "Paris"}}. That is a request to run a tool.
  3. The runner calls get_time(city="Paris"), which returns "12:00 in Paris". It appends tool: "12:00 in Paris" to the messages.
  4. Turn 2. The last message is now from the tool, so the model replies {"final": "It is 12:00 in Paris"}.
  5. The runner sees final and returns it. The printed output is It is 12:00 in Paris.

The loop took 2 turns. max_turns=5 would have stopped it with an error if the model kept asking for tools. A real SDK does the same, with a real model. Check the current docs for exact imports.

Code example

From scratch, stdlib only, with a scripted fake model:

def get_time(city): return f"12:00 in {city}"
TOOLS = {"get_time": get_time}

def fake_model(messages):
    if messages[-1]["role"] == "user":
        return {"tool": "get_time", "args": {"city": "Paris"}}
    return {"final": "It is " + messages[-1]["content"]}

def run(user_input, max_turns=5):
    messages = [{"role": "user", "content": user_input}]
    for _ in range(max_turns):
        out = fake_model(messages)
        if "final" in out:
            return out["final"]
        result = TOOLS[out["tool"]](**out["args"])
        messages.append({"role": "tool", "content": result})
    raise RuntimeError("too many turns")

print(run("What time is it in Paris?"))   # It is 12:00 in Paris

In real projects (pip install openai-agents, needs OPENAI_API_KEY):

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a concise assistant.")
result = Runner.run_sync(agent, "Write a haiku about recursion.")
print(result.final_output)

Tools, handoffs and guardrails are added through Agent options; see the docs for the current forms.

When to use it / when not to

Common mistakes

Recap

If you remember only three things:

Interview questions

  1. What does the Runner do? <details><summary>Answer</summary>It runs the agent loop: call the model, execute requested tools, apply handoffs, and stop at a final output or turn limit.</details>
  2. What is a handoff? <details><summary>Answer</summary>Transfer of the conversation from one agent to a more suitable agent, such as triage to billing.</details>
  3. Why have tracing? <details><summary>Answer</summary>Agent runs are multi-step and non-deterministic. A trace of each call lets you find which step went wrong.</details>

Go deeper

Prev: LlamaIndex · Next: CrewAI · Back to phase: Phase 5