The Complete OpenAI Agents SDK Guide

This is part one of three. It covers everything you need to build a working agent with the OpenAI Agents SDK, not a teaser. By the end you can define an agent, give it Python functions it can call, make it return a typed object instead of loose prose, route a question to a specialist agent, keep a conversation going across turns, stream tokens to a user, stop a request you do not want to serve, and read the stack trace when any of that goes wrong. The Mid-level and Senior guides take the same topics further into production; nothing you learn here is thrown away.

Every section ends with a Try it task. Do them as you go. Agents are one of those subjects where the vocabulary sounds obvious and the behaviour is not, and the gap closes only once you have watched your own agent call a tool, hand off to another agent, and loop ten times before giving up.

The version this guide was verified against is openai-agents 0.22.3, released 17 September 2026. The SDK is young and moves fast, and some of what you will read in older blog posts is now wrong, so a few places in this guide say explicitly "this changed".

What the OpenAI Agents SDK is, and the problem it solves

An agent in this context is a language model that has been given a job description, a set of actions it can take, and permission to decide for itself which action to take next. That last part is what separates an agent from a single API call. When you call a chat completion endpoint directly, you get one response and you are done. When you run an agent, the model may answer immediately, or it may decide to look something up first, call a function you wrote, read the result, call another function, and only then answer.

Somebody has to run that back-and-forth. Something has to take the model's request to call get_order_status, find the matching Python function, validate the arguments the model invented, call the function, catch the exception if it throws, put the result back into the conversation in the exact shape the API expects, call the model again, and decide when the whole thing is finished. That loop is not conceptually hard, but it is a few hundred lines of fiddly code that every team was writing from scratch and getting slightly wrong.

The OpenAI Agents SDK is that loop, written once, as a small Python library. You describe the agent; the SDK runs the loop. It is the production successor to Swarm, an earlier experimental OpenAI project, and by default it talks to the OpenAI Responses API and wraps it in a runtime.

The SDK's own documentation gives a clean rule for when to use it at all, and it is worth internalising before you write a line of code. Call the Responses API directly if you want to own the loop, the tool dispatch and the state yourself — if you are building something unusual and the loop is the interesting part of your product. Use the SDK if you want the runtime to handle turns, tools, guardrails, handoffs, sessions or sandboxes, so that the interesting part of your product can be your tools and your prompts.

Two design decisions shape everything that follows, and both are easier to accept now than to discover by accident later.

It is a library, not a server. There is no agent daemon to install, no control plane, no dashboard you deploy. The SDK runs inside your own Python process — a FastAPI handler, a Celery worker, a script on your laptop. This is why there is nothing to configure beyond environment variables, and why questions like "where does conversation history live?" have the answer "wherever you decide to put it".

The primitive set is deliberately tiny. There are only a handful of concepts: agents, tools, handoffs, guardrails, sessions, and a runner that ties them together. Frameworks in this space often ship dozens of abstractions; this one ships about six, on the theory that you can read all of them in an afternoon and then predict what your program will do. That bet mostly pays off, and the small vocabulary is the main reason the SDK is a good first agent framework even if you later move to something else.

The four nouns: Agent, Runner, Tool, Handoff

Nearly every sentence in the SDK documentation uses one of four words in a precise sense. Getting them straight now saves a great deal of confusion.

An Agent is a configured LLM. You create one with Agent(name=..., instructions=..., tools=..., ...). The instructions field is what other frameworks call the system prompt: the standing brief the model sees on every call. name is not cosmetic — it appears in traces, and when one agent hands off to another the handoff tool is named after it. An agent also optionally carries handoffs, guardrails, an output_type, a model name and model settings. An agent object is cheap and inert; creating one makes no network call.

A Runner is what actually executes an agent. It is a class with three entry points you will use constantly: Runner.run(...) which is async and is what you should reach for by default, Runner.run_sync(...) which is a synchronous wrapper for scripts and notebooks-that-are-not-notebooks, and Runner.run_streamed(...) which returns a streaming result you iterate over. All three run the same loop.

A Tool is anything the model can call. The kind you will write first is a function tool: an ordinary Python function with a decorator on it. The SDK reads the function's name, its docstring and its type hints, and from those builds the JSON schema the model needs in order to call it correctly. There are other kinds — tools hosted by OpenAI such as web search, local runtime tools such as a shell, tools exposed by an MCP server, and even other agents wrapped as tools — but a decorated function is the one that will do ninety percent of your work.

A Handoff is delegation in which the other agent takes over the conversation. The model sees a handoff as a tool named transfer_to_<agent_name>, and when it calls that tool the runner swaps in the target agent and keeps looping. Handoffs stay inside a single run, which means one call to Runner.run can begin with a triage agent and finish with a billing specialist.

The distinction you must not blur is handoff versus agent-as-tool, because both look like "one agent uses another agent" and they behave very differently. With a handoff, control and the conversation move to the specialist, and when the run finishes result.last_agent is the specialist, not the agent you started with. With an agent-as-tool — created by calling agent.as_tool(tool_name=..., tool_description=...) — the orchestrating agent calls the specialist the way it would call any function, gets a string back, and keeps control. The nested run receives input the orchestrator generated for it, and its state does not inherit the parent's conversation history unless you deliberately pass the same session.

The agent loop, turn by turn

Everything the runner does is one loop with three exits. It is short enough to memorise, and memorising it makes the SDK's behaviour predictable instead of magical.

1. Call the modelThe runner calls the LLM for the current agent, with the current input: the instructions, the conversation so far, and the schemas of every tool the agent has.
2. Is the output final?If the model returned text of the desired output_type and made no tool calls, the run is over and that text is the result. Both halves matter: text accompanied by a tool call is not final.
3. Is it a handoff?If the model called a transfer_to_* tool, the runner switches the current agent to the target and loops back to step one.
4. Are there tool calls?If so, the runner executes them, appends their results to the conversation, and loops back to step one.
5. Have we looped too long?If the number of model calls exceeds max_turns, the runner raises MaxTurnsExceeded.

The word that trips up almost every newcomer is turn. A turn is one model call, not one user message. If a user asks a single question and the agent calls three tools before answering, that is four turns, not one. max_turns defaults to 10, so an agent that gets stuck calling the same tool repeatedly will blow up after ten model calls rather than running forever and charging you for it. You can raise the number, and since version 0.16.0 you can pass max_turns=None to remove the limit entirely — which you should do only when you have some other way of stopping the loop.

The result object you get back has a few fields you will reach for immediately. result.final_output holds the answer: a str if the last agent had no output_type, otherwise an instance of that type. It is typed as Any, which looks sloppy until you remember that a handoff can change which agent finishes the run, so the static type genuinely is not knowable. result.last_agent tells you which agent produced the answer. result.to_input_list() gives you the whole conversation as a list of input items, which is how you do multi-turn chat by hand. And result.context_wrapper.usage carries token counts, which is how you find out what a run cost.

One subtlety about final_output: it can be None. That happens when the run paused rather than finished — most commonly because a tool needs human approval. That is a Senior-level topic, but it is worth knowing that None means "not finished", not "the model said nothing".

Installing the SDK and checking your setup

The package is named openai-agents and you import it as agents. Getting those two names mixed up produces a confusing ModuleNotFoundError, so note it once: install openai-agents, import agents. Python 3.10 or newer is required; support for 3.9 was dropped in version 0.9.0, and the current release is tested on 3.10 through 3.14.

On macOS or Linux:

mkdir my_project && cd my_project
python -m venv .venv
source .venv/bin/activate
pip install openai-agents          # or: uv init && uv add openai-agents
export OPENAI_API_KEY=sk-...

On Windows the activation step differs and the environment variable is set differently depending on your shell:

python -m venv .venv
.venv\Scripts\activate
pip install openai-agents
$env:OPENAI_API_KEY = "sk-..."

set "OPENAI_API_KEY=sk-..."

The virtual environment is not optional busywork. The SDK pins its dependencies fairly tightly — at 0.22.3 it requires openai 3.x and pydantic 2.x — and installing it into a system Python alongside an older openai library is the single most common way to end up with an import error that has nothing to do with your code.

Check that the install worked before you write anything:

python -c "import agents, importlib.metadata as m; print(m.version('openai-agents'))"
pip show openai-agents

The first command should print 0.22.3. If it prints an older version, you have an old pin somewhere; if it raises ModuleNotFoundError: No module named 'agents', your shell is using a different Python than the one you installed into, which is almost always a forgotten source .venv/bin/activate.

Then make a real call, which is the only way to confirm that your API key works:

from agents import Agent, Runner

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

Three lines, one network call, and a haiku. If that prints, you are set up. If it raises an error about a missing API key, the key is not in the environment of the process you just ran — check echo $OPENAI_API_KEY in the same terminal.

The SDK ships a number of optional extras for things you do not need on day one, and it is useful to know they exist so you recognise them in other people's code: voice, realtime, viz for drawing agent graphs with Graphviz, redis, sqlalchemy, mongodb, docker, litellm and any-llm for non-OpenAI models, and a set of hosted sandbox providers. Install them with bracket syntax, and always quote the brackets, because zsh on macOS will otherwise try to expand them as a glob pattern and fail with a cryptic no matches found:

pip install "openai-agents[voice]"
pip install "openai-agents[redis,sqlalchemy]"
pip install "openai-agents[viz]"        # also needs the Graphviz system binary

Your first agent, properly

The haiku script used Runner.run_sync because it is the shortest thing that works. Real code should use the async form, so write that version next and get used to it:

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

async def main():
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)

asyncio.run(main())

There is a trap in run_sync that is worth understanding properly, because it accounts for a large share of the confused questions newcomers ask. Runner.run_sync works by starting an event loop, running the async code inside it, and returning the result. If an event loop is already running in your process, it cannot do that, and it raises:

AgentRunner.run_sync() cannot be called when an event loop is already running.

The places you will meet this are Jupyter notebooks, FastAPI route handlers, discord.py or aiogram bot callbacks, and anywhere else inside async def. The fix is always the same: use await Runner.run(...) instead. run_sync is for scripts and tests, not for servers.

Giving the agent tools

An agent with no tools can only talk. Tools are how it does things, and in this SDK a tool is an ordinary Python function with a decorator:

import asyncio
from agents import Agent, Runner
from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Return weather info for the specified city."""
    return f"The weather in {city} is sunny"

agent = Agent(
    name="Weather",
    instructions="Use tools when helpful.",
    tools=[get_weather],
)

async def main():
    result = await Runner.run(agent, "What should I wear in Cairo today?")
    print(result.final_output)

asyncio.run(main())

Read what the decorator did, because it did more than it looks. The tool name comes from the function name, so the model sees a tool called get_weather. The description comes from the docstring, parsed with the griffe library, which is why that one-line docstring is not decoration — it is the only explanation the model gets of what the tool is for. The parameter schema comes from the type hints, converted to JSON Schema by Pydantic, which is why city: str matters and a bare city would not work nearly as well.

The practical consequence is that the quality of your tool docstrings and type hints is the quality of your agent's tool use. If the model keeps calling a tool with nonsense arguments, your first move should not be prompt surgery on the instructions; it should be rewriting the docstring to say what the parameter means, and tightening the type hint so the schema constrains it.

You will see two spellings of the decorator in the wild. @function_tool is the original, and @tool was added in version 0.19.0 as an alias in the new agents.decorators module. Neither is deprecated, both do exactly the same thing, and the current documentation uses @tool. This guide uses @tool; if you are reading older tutorials and see from agents import function_tool, it is the same decorator.

A handful of options on the decorator are worth knowing early, even if you do not use them today:

The failure_error_function behaviour is counter-intuitive and worth pinning down. If you leave it alone, an exception inside your tool does not crash the run: the SDK catches it and sends the model the text "An error occurred while running the tool. Please try again.", and the loop continues. If you pass failure_error_function=None explicitly, the exception is re-raised and your run fails loudly. Leaving it out and passing None are therefore different things, which is a genuinely surprising API, and the distinction matters the first time you want a failing database call to fail your request instead of being quietly explained to the model.

Both synchronous and asynchronous functions work as tools. Since version 0.8.0 synchronous tools are run in worker threads, so a slow blocking call will not freeze the event loop — but it will still occupy a thread, so genuinely I/O-heavy tools are better written async def.

Finally, a tool can reach your application's own data. If the first parameter is annotated ctx: RunContextWrapper[T], the SDK passes in the context object you handed to Runner.run(..., context=obj), and your tool reads it at ctx.context. The crucial property of that context is that it is never sent to the LLM. It is the right place for a database handle, the logged-in user's ID, or a tenant identifier — things your tools need and the model has no business seeing.

Structured output you can trust

Most of the time you do not actually want prose back. You want a record you can put in a database, and parsing it out of a paragraph with a regular expression is how you end up with a 3am incident. The SDK handles this with output_type: give the agent a Pydantic model, and result.final_output becomes an instance of that model.

import asyncio
from pydantic import BaseModel
from agents import Agent, Runner

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

agent = Agent(
    name="Calendar extractor",
    instructions="Extract calendar events",
    output_type=CalendarEvent,
)

async def main():
    result = await Runner.run(
        agent,
        "Aya and Omar are meeting about the Q4 roadmap on 12 November.",
    )
    event = result.final_output
    print(event.name, event.date, event.participants)

asyncio.run(main())

Under the hood the SDK converts your model to a JSON schema and asks the API to constrain the model's output to it. The validation happens before you see the result, so if final_output is a CalendarEvent, the fields really are there and really are the declared types. This is a much stronger guarantee than "I asked the model to reply in JSON and it usually does".

Remember from the loop that the definition of a final output is "text of the desired output_type and no tool calls". With an output_type set, an agent can still call tools as many times as it likes; the structured object is only produced on the turn where it decides it is finished.

Strict schemas are the default, and they come with real constraints that produce an error message you should learn to recognise. A strict JSON schema must have a non-nullable object at its root. So a free-form dict[str, Any] as your output_type, or a Union of two models at the top level, will be rejected with a UserError that says something like "The root of a strict JSON schema must be a non-nullable object" or "must not use anyOf". The fix is nearly always to wrap the thing you wanted in a Pydantic model with named fields — which is better design anyway, because now the model knows what you are asking for.

Handing off to a specialist

One agent with twenty tools and a two-page brief behaves worse than three agents with clear jobs. Handoffs are how you split the work.

import asyncio
from agents import Agent, Runner, handoff
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

history_tutor = Agent(
    name="History Tutor",
    handoff_description="Specialist agent for historical questions",
    instructions="You answer history questions clearly and concisely.",
)

math_tutor = Agent(
    name="Math Tutor",
    handoff_description="Specialist agent for math questions",
    instructions="You explain math step by step.",
)

triage = Agent(
    name="Triage Agent",
    instructions=(
        f"{RECOMMENDED_PROMPT_PREFIX}\n"
        "Route each homework question to the right specialist."
    ),
    handoffs=[history_tutor, handoff(math_tutor)],
)

async def main():
    result = await Runner.run(triage, "Who was the first president?")
    print(result.last_agent.name)
    print(result.final_output)

asyncio.run(main())

Three details in that snippet are doing specific work.

handoff_description is the text the triage agent sees when deciding where to route. It is to a handoff what a docstring is to a tool: the only description available. An agent that routes badly usually has vague handoff descriptions, not a bad router prompt.

RECOMMENDED_PROMPT_PREFIX is a block of boilerplate the SDK ships that explains the handoff mechanism to the model — essentially, "you are part of a multi-agent system, here is how transferring works". Models route noticeably better with it, and prepending it costs you one import.

The handoffs list accepts either an agent directly or handoff(agent). They are equivalent until you need options, and handoff() is where the options live: tool_name_override if you dislike the generated transfer_to_math_tutor, tool_description_override, an on_handoff callback that fires when the transfer happens, an input_filter that lets you trim the history the specialist receives, and is_enabled to turn a route off dynamically. Start with the bare agent and reach for handoff() when you need one of those.

Because result.final_output is produced by whichever agent finished, an output_type set only on your triage agent will not apply when a specialist answers. If every route must return the same structured shape, set output_type on every agent that can finish a run. This catches people out regularly.

Remembering the conversation

Each call to Runner.run is independent. The agent has no memory of the previous call unless you give it one, so the second question in a conversation needs the first question's context passed in somehow.

The manual way is explicit and sometimes exactly right:

result = await Runner.run(agent, "What city is the Golden Gate Bridge in?")
new_input = result.to_input_list() + [
    {"role": "user", "content": "What state is it in?"}
]
result = await Runner.run(agent, new_input)
print(result.final_output)

to_input_list() returns the whole run — the user message, the model's messages, any tool calls and their results — as a list of input items. Append the next user message and pass the list as the input. You now own the history, which means you can trim it, store it, or redact it however you like.

The easier way is a session, a memory layer that loads history before each run and saves the new items afterwards:

import asyncio
from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

async def main():
    session = SQLiteSession("user_123", "conversations.db")
    r1 = await Runner.run(agent, "What city is the Golden Gate Bridge in?", session=session)
    print(r1.final_output)
    r2 = await Runner.run(agent, "What state is it in?", session=session)
    print(r2.final_output)

asyncio.run(main())

The second question works because the session replayed the first exchange into the model's input. SQLiteSession("conversation_123") with no filename keeps everything in memory for the lifetime of the process; adding a filename makes it a real file you can inspect with the sqlite3 CLI, which is genuinely useful when debugging "why did the agent think that?".

The session ID is the conversation key, and in any multi-user application it must be derived from your authenticated user — one session per user or per thread. Note carefully that a session ID is not authentication: if you take it from a request body and trust it, any caller can read any conversation. Authorise first, then pick the session ID from the authorised identity.

SQLiteSession is for development. The SDK ships other backends for production — Redis, SQLAlchemy over Postgres, MongoDB, and OpenAI's own server-side Conversations API — and swapping between them is a one-line change because they all implement the same protocol. Which to choose, and the data-residency questions that come with it (a Gulf or Egyptian employer with a local-storage requirement will want the conversation history in a Postgres they control rather than in a vendor's conversation store), is a Mid-level topic.

Streaming, and the throwaway REPL

Users will tolerate a slow answer that is visibly arriving and will not tolerate a spinner. Streaming is how you give them the first.

import asyncio
from openai.types.responses import ResponseTextDeltaEvent
from agents import Agent, Runner

agent = Agent(name="Joker", instructions="You are a joker.")

async def main():
    result = Runner.run_streamed(agent, input="Please tell me 5 jokes.")
    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            print(event.data.delta, end="", flush=True)

asyncio.run(main())

The first thing to notice is that Runner.run_streamed is not awaited. It returns a result object immediately, and the work happens as you iterate stream_events(). Putting an await in front of it is a common early mistake.

There are three event types. raw_response_event carries the low-level model events, including the text deltas you just printed. run_item_stream_event carries higher-level happenings — a message was produced, a tool was called, a tool returned, a handoff was requested — and its name field takes one of a fixed set of values including message_output_created, tool_called, tool_output, handoff_requested and, spelled exactly like this, handoff_occured. That misspelling is deliberate and preserved for backward compatibility; do not "fix" it in your code, because the fixed spelling does not exist. The third type, agent_updated_stream_event, fires when a handoff changes the current agent, which is how you show a user "transferring you to billing".

The rule that catches people out: drain stream_events() to the end. The last token is not the end of the run. Session writes, approval bookkeeping and history compaction all happen after the final token, so if you break out of the loop as soon as you have the text you want, you can silently lose the conversation history you thought you were saving. If a stream appears to hang for a second or two after the last word, that is this post-processing, not a bug.

For exploration there is something even easier. run_demo_loop gives you an interactive terminal chat with your agent in one line:

import asyncio
from agents import Agent, run_demo_loop

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

asyncio.run(run_demo_loop(agent))

It streams by default, keeps the conversation going across turns, and exits when you type quit or exit or press Ctrl-D. This is the fastest way to get a feel for whether your instructions and tools actually work, and it is much more informative than re-running a script with one hard-coded question.

Guardrails: your first safety net

Some requests should not reach your agent at all, and some answers should not reach your user. A guardrail is a function that inspects the input or the output and can stop the run by returning a tripwire.

from pydantic import BaseModel
from agents import (
    Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered,
    RunContextWrapper, Runner, TResponseInputItem,
)
from agents.decorators import input_guardrail

class HomeworkCheck(BaseModel):
    is_math_homework: bool

guardrail_agent = Agent(
    name="Homework check",
    instructions="Decide whether the user is asking you to do their maths homework.",
    output_type=HomeworkCheck,
)

@input_guardrail
async def math_guardrail(
    ctx: RunContextWrapper[None],
    agent: Agent,
    input: str | list[TResponseInputItem],
) -> GuardrailFunctionOutput:
    result = await Runner.run(guardrail_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math_homework,
    )

support = Agent(
    name="Support",
    instructions="You help with study-skills questions.",
    input_guardrails=[math_guardrail],
)

Then you catch the tripwire where you call the agent:

try:
    result = await Runner.run(support, "solve 2x+3=11")
    print(result.final_output)
except InputGuardrailTripwireTriggered as e:
    print("Refused:", e.guardrail_result.output.output_info)

A guardrail returns GuardrailFunctionOutput(output_info=..., tripwire_triggered=bool). The output_info is whatever you want to record about the decision — it ends up on the exception and in the trace, so put the reason in there. When tripwire_triggered is True, the run stops with InputGuardrailTripwireTriggered (or the output equivalent), and it is your job to catch that and say something sensible to the user.

Two facts about when guardrails run will save you real debugging time. Input guardrails run only on the first agent of a run — not on each agent after a handoff. Output guardrails run only on the agent that produces the final output. So in the triage example, an input guardrail on the triage agent protects the whole run, and an output guardrail belongs on each specialist that can finish.

And one about cost. By default input guardrails run in parallel with the agent, which is good for latency but means that by the time the tripwire fires, your agent may already have spent tokens and possibly run a tool. If the cost or the side effect matters, decorate with @input_guardrail(run_in_parallel=False) and the guardrail runs first and blocks. A cheap fast model for the guardrail agent, in blocking mode, is the standard shape for a moderation check.

Output guardrails have no parallel option — they cannot, since they need the output — and their signature is (ctx, agent, output).

Choosing a model, and the settings that matter

If you do not specify a model, the SDK uses its default. As of version 0.20.0 that default is gpt-5.6-luna, which replaced gpt-5.4-mini; implicit defaults of reasoning.effort="none" and verbosity="low" go with it. Any guide you read that names an older default is out of date.

You can set the model in three places, and they have a strict precedence. From highest to lowest: an explicit model on the agent, then RunConfig.model for a single run, then the OPENAI_DEFAULT_MODEL environment variable, then the SDK default.

from agents import Agent, RunConfig, Runner

agent = Agent(name="A", model="gpt-5.6-sol")                 # per agent, highest priority

# or per run:
result = await Runner.run(agent, "Hi", run_config=RunConfig(model="gpt-5.6-sol"))

export OPENAI_DEFAULT_MODEL=gpt-5.6-sol

The habit to adopt now, before it costs you anything, is to set the model explicitly in anything you deploy. The SDK default has changed twice in recent minor versions. If you rely on it, an unrelated dependency bump can silently change which model serves your users, along with your latency and your bill. Explicit beats implicit here for the same reason you pin dependency versions.

Per-run and per-agent LLM parameters live in ModelSettings. You will not need most of its fields on day one, but four of them come up constantly:

from agents import Agent, ModelSettings

agent = Agent(
    name="Summariser",
    instructions="Summarise the input in three bullet points.",
    model="gpt-5.6-luna",
    model_settings=ModelSettings(
        temperature=0.2,
        max_tokens=500,
        timeout=30.0,
        tool_choice="auto",
    ),
)

temperature you already know. max_tokens caps the output. timeout is in seconds and limits each model attempt, raising ModelTimeoutError if it is exceeded — worth setting, because the default is no timeout at all and a hung model call will hang your request. tool_choice controls whether the model may call tools: "auto" is the default, "required" forces it to call something, "none" forbids tools, and a tool's name forces that specific tool.

tool_choice="required" deserves a warning. Forcing a tool call on every turn is an easy way to build an infinite loop, since the model must call a tool, which produces a result, which triggers another turn, which must call a tool. The SDK protects you with reset_tool_choice, which defaults to True and clears the forced choice after a tool runs. If you ever turn that off, max_turns becomes your only backstop.

One note on retries, because it surprises people: the SDK does not retry model calls unless you configure ModelSettings.retry. There is no hidden layer absorbing transient 429s for you.

Reading the errors you will actually hit

Every exception the SDK raises inherits from AgentsException, so you can catch that as a backstop. But the specific ones carry the information, and learning to read five of them makes you dramatically faster at this.

MaxTurnsExceeded is the one you will see most, and it is almost always a symptom rather than a cause. Ten model calls for one question means the agent is going in circles: a tool that returns something the model does not understand, so it calls it again; instructions that tell it to verify everything twice; or tool_choice="required" with the loop protection disabled. Before you raise the limit, look at the trace and count what it actually did. If you genuinely need a long-running agent, you can set max_turns higher or to None, and you can install a graceful fallback:

from agents import RunErrorHandlerResult, Runner

result = Runner.run_sync(
    agent,
    "Research the entire history of shipping.",
    max_turns=3,
    error_handlers={
        "max_turns": lambda d: RunErrorHandlerResult(
            final_output="That's too broad for me — can you narrow it down?",
            include_in_history=False,
        ),
    },
)

Two behaviours changed recently enough that older code gets them wrong. Since version 0.15.0, a model refusal raises ModelRefusalError with the refusal text on .refusal; before that it came back as an empty final_output or looped until the turn limit, so code that checks if not result.final_output to detect refusals is now checking the wrong thing. And as noted above, since 0.22.0 a non-streaming Responses call that ends failed or incomplete raises ModelBehaviorError rather than returning a partial result.

Finally, when you are stuck and the exception is not telling you enough, turn on verbose logging:

from agents import enable_verbose_stdout_logging

enable_verbose_stdout_logging()

That prints what the SDK is sending and receiving, through the openai.agents logger. Note that model and tool payloads are redacted by default — controlled by the OPENAI_AGENTS_DONT_LOG_MODEL_DATA and OPENAI_AGENTS_DONT_LOG_TOOL_DATA environment variables, which both default to redacting. Setting one to 0 shows you the actual arguments the model invented, which is often exactly what you need when a tool keeps receiving nonsense. Do that in development only; those payloads contain user data.

Seeing what happened: tracing

An agent run is a sequence of decisions you did not make, which makes "why did it do that?" the central debugging question. The SDK answers it with tracing, and the good news is that tracing is on by default: every run you have done in this guide has already produced a trace at https://platform.openai.com/traces.

The vocabulary is small. A trace is one end-to-end workflow, named "Agent workflow" unless you say otherwise. A span is one step inside it, and the SDK emits spans for the agent, each model generation, each function call, each guardrail and each handoff. Open a trace and you see the tree: this agent ran, it called the model, the model called get_weather with these arguments, the tool returned this, the model answered. Nearly every "why did it do that?" is answered by looking at that tree for sixty seconds.

Two things are worth setting even at beginner level:

from agents import RunConfig, Runner

result = await Runner.run(
    agent,
    "Where is my order?",
    run_config=RunConfig(
        workflow_name="Support triage",
        group_id=thread_id,
    ),
)

workflow_name means your traces are findable by name instead of being a hundred identical entries called "Agent workflow". group_id ties the separate runs of one conversation together, so a chat thread ID is the natural value.

You can turn tracing off globally with the OPENAI_AGENTS_DISABLE_TRACING=1 environment variable, or per run with RunConfig(tracing_disabled=True). There are two situations where you must think about this. If your organisation is on Zero Data Retention, OpenAI tracing is not available to you at all, and you need a third-party processor instead — the SDK supports a long list of them, including Langfuse, MLflow, Arize Phoenix and LangSmith, all of which have their own guides or near-equivalents in this catalogue. And if your data cannot leave a particular jurisdiction — a real constraint for banks and government work in the Gulf and in Egypt — then sending prompt contents to a tracing dashboard is a decision to make deliberately, not a default to inherit. RunConfig(trace_include_sensitive_data=False) keeps the shape of the trace while leaving the contents out.

Putting it all together

Here is one small end-to-end project that uses everything above: a support assistant with a tool, structured output, a handoff, a session and a guardrail. It is short enough to read in one sitting and complete enough to be a template.

import asyncio
from dataclasses import dataclass

from pydantic import BaseModel
from agents import (
    Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered,
    ModelSettings, RunConfig, RunContextWrapper, Runner, SQLiteSession,
    TResponseInputItem, handoff,
)
from agents.decorators import input_guardrail, tool
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX


@dataclass
class AppContext:
    """Never sent to the model. Holds who is asking and how to look things up."""
    user_id: str
    orders: dict[str, str]


class Reply(BaseModel):
    answer: str
    needs_human: bool


@tool
def get_order_status(ctx: RunContextWrapper[AppContext], order_id: str) -> str:
    """Look up the delivery status of one order by its ID."""
    orders = ctx.context.orders
    if order_id not in orders:
        return f"No order {order_id} found for this account."
    return f"Order {order_id}: {orders[order_id]}"


@input_guardrail(run_in_parallel=False)
async def no_secrets(
    ctx: RunContextWrapper[AppContext],
    agent: Agent,
    input: str | list[TResponseInputItem],
) -> GuardrailFunctionOutput:
    text = input if isinstance(input, str) else str(input)
    leaked = "sk-" in text
    return GuardrailFunctionOutput(
        output_info="API key in message" if leaked else "clean",
        tripwire_triggered=leaked,
    )


refunds = Agent[AppContext](
    name="Refunds Agent",
    handoff_description="Handles refund requests and money back questions",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nExplain the refund policy and next steps. Never promise a date.",
    output_type=Reply,
    model="gpt-5.6-luna",
)

triage = Agent[AppContext](
    name="Support Agent",
    instructions=(
        f"{RECOMMENDED_PROMPT_PREFIX}\n"
        "You are a support agent for an online store. "
        "Use get_order_status before stating anything about a delivery. "
        "Hand off refund requests to the Refunds Agent. "
        "Set needs_human when you cannot resolve the question."
    ),
    tools=[get_order_status],
    handoffs=[handoff(refunds)],
    input_guardrails=[no_secrets],
    output_type=Reply,
    model="gpt-5.6-luna",
    model_settings=ModelSettings(temperature=0.2, timeout=30.0),
)


async def main() -> None:
    ctx = AppContext(user_id="u-42", orders={"A100": "out for delivery in Riyadh"})
    session = SQLiteSession(f"support:{ctx.user_id}", "support.db")
    config = RunConfig(workflow_name="Support triage", group_id=ctx.user_id)

    for question in [
        "Where is order A100?",
        "It arrived damaged, I want my money back.",
    ]:
        try:
            result = await Runner.run(
                triage, question, context=ctx, session=session, run_config=config
            )
            reply: Reply = result.final_output
            print(f"[{result.last_agent.name}] {reply.answer}")
            if reply.needs_human:
                print("  -> escalating to a human")
            print("  tokens:", result.context_wrapper.usage.total_tokens)
        except InputGuardrailTripwireTriggered as exc:
            print("Refused:", exc.guardrail_result.output.output_info)


asyncio.run(main())

Walk through what each piece earns. AppContext carries the user ID and the order lookup; because context is never sent to the model, the model cannot see other users' orders even if it asks. The tool takes ctx as its first parameter and reads from that context, so it can only look up orders for the authenticated account — authorisation inside the tool, exactly as the warning earlier insisted. Reply makes the output a typed object with an escalation flag, so your calling code branches on a boolean rather than searching prose for the phrase "speak to a human". output_type is set on both agents, because either can finish the run. The guardrail runs in blocking mode because the point is to stop before spending anything. The session key is derived from the authenticated user, not from user input. And RunConfig names the workflow and groups the runs so the traces are navigable.

What you can now do, and what comes next

You can define an agent with instructions, tools and a model; run it synchronously, asynchronously or as a stream; make it return a validated Pydantic object; route between specialists with handoffs and know when to use as_tool instead; keep a conversation with a session; block requests with a guardrail; set the model and its settings explicitly rather than inheriting defaults; read the five errors that account for most beginner pain; and open a trace to find out what your agent actually did. That is a working, debuggable agent, and it is genuinely most of what day-to-day SDK work consists of.

Three habits are worth carrying forward from here, because they stay correct at every level. Set the model explicitly, so a dependency bump cannot change your product. Pin the minor version with openai-agents~=0.22.3, because minor releases may break public APIs. Read the trace before changing the prompt, because the trace usually tells you that the problem was a tool schema, not persuasion.

The Mid-level guide picks up where the defaults stop being good enough: how the loop behaves under load, tool_use_behavior and forcing tool choice, dynamic instructions, the full RunConfig surface, MCP servers as a tool source, production session backends, lifecycle hooks, retry and timeout policies, non-OpenAI models through LiteLLM, and deterministic testing with agents.testing.ScriptedModel. The Senior guide covers human-in-the-loop approvals and serialising RunState, the security model around that state, multi-tenancy, cost control, sandbox agents, and upgrade strategy across breaking minors.

Sideways, the natural neighbours in this catalogue are LangGraph if you want explicit graph control over the loop instead of letting the model decide, MCP for the protocol behind tool servers you did not write, Langfuse for tracing you host yourself, RAGAS for evaluating whether your agent is actually any good, and FastAPI for the service you will almost certainly wrap it in. The OpenAI API guide covers the Responses API underneath all of this, which is useful the first time you need to understand an error the SDK is merely relaying.

Sources

• OpenAI Agents SDK documentation
• Quickstart
• Agents
• Running agents
• Results
• Streaming
• Tools
• Handoffs
• Orchestrating multiple agents
• Guardrails
• Context management
• Sessions
• Models
• Configuring the SDK
• Tracing
• Usage
• REPL
• Release process and breaking changes
• openai-agents on PyPI
• openai/openai-agents-python on GitHub

This is the interview companion to the Beginner guide. It assumes you have read that guide, or at least built one agent. The goal is narrow and practical: to make sure that when somebody asks you "so what is the OpenAI Agents SDK?" in the first five minutes of a screening call, you give an answer that sounds like you have used it rather than read about it.

Junior and mid-level interviews for agent work are rarely about exotic features. They are about whether you know what a turn is, whether you understand that the model decides and your code executes, and whether you have ever debugged an agent that went in circles. Those three things come up constantly. Everything below is organised around them.

The thirty-second answer

The OpenAI Agents SDK is a small Python library that runs the agent loop for you: you describe an agent with instructions, tools and a model, and the SDK handles calling the model, dispatching tool calls, routing handoffs between agents and deciding when the run is finished. It is a library rather than a server — it runs inside your own process — and it talks to the OpenAI Responses API by default.

That is two sentences and it covers the three things an interviewer is listening for: what it does (runs the loop), what you give it (agents, tools, models), and what it is not (a service you deploy).

If they want a follow-up sentence, the useful one is the SDK's own framing of when to use it: call the Responses API directly if you want to own the loop and the state yourself; use the SDK if you want the runtime to handle turns, tools, guardrails, handoffs and sessions. Saying that signals you know the SDK is a choice rather than a requirement, which is exactly the maturity a hiring manager is probing for.

Add one concrete anchor if you have it. "I built a support triage agent with two tools and a handoff to a refunds agent, with a SQLite session for history" lands far better than any amount of accurate abstraction, because it proves you have seen the thing run.

The model, in the words an interviewer uses

You should be able to define these six terms crisply and without hedging. Vague definitions here are the most common reason a candidate who has genuinely built something still sounds unsure.

Agent. An LLM plus configuration: instructions (the standing brief, what other frameworks call the system prompt), tools, optional handoffs, an optional output_type, a model and model_settings. Creating one makes no network call; it is just configuration.

Runner. The thing that executes an agent. Runner.run is async and the default choice, Runner.run_sync is a synchronous wrapper for scripts, and Runner.run_streamed returns a streaming result you iterate. All three run the same loop.

Turn. One model call. Not one user message. This is the definition interviewers most enjoy checking, because getting it wrong reveals that you have not watched a run. If an agent calls three tools before answering, that is four turns. max_turns defaults to 10, and None disables the limit.

Tool. Anything the model can call. The most common kind is a function tool: a Python function with @tool on it, where the name comes from the function name, the description from the docstring, and the parameter schema from the type hints via Pydantic.

Handoff. Delegation in which the other agent takes over the conversation. The model sees it as a tool called transfer_to_<agent_name>. Handoffs stay inside one run, so one Runner.run call can start at triage and finish at a specialist.

Guardrail. A validation function returning GuardrailFunctionOutput(output_info=..., tripwire_triggered=bool). A triggered tripwire raises and stops the run.

And one distinction that is worth rehearsing out loud, because it is the most-asked design question at this level. Handoff versus agent-as-tool: with a handoff, control and history move to the specialist and result.last_agent is the specialist. With agent.as_tool(...), the orchestrator calls the specialist like a function, gets a result back, and keeps control. The one-line test is who should be talking to the user when the run ends — if the specialist, use a handoff; if the original agent, use as_tool.

The loop, which you will be asked to draw

A whiteboard or a verbal trace of the loop is a standard exercise. Say it in five steps:

1. Call the model for the current agent with the current input.
2. If the output is text of the desired output_type and there are no tool calls, it is final — return it.
3. If the output is a handoff, switch the current agent and loop.
4. If there are tool calls, run them, append the results, and loop.
5. If the number of model calls exceeds max_turns, raise MaxTurnsExceeded.

Two details raise the quality of that answer noticeably. First, emphasise the "and no tool calls" half of step two — text accompanied by a tool call is not a final output, and candidates who skip this usually cannot then explain why a run took six turns. Second, mention that each turn is a billable model call, which is why the default limit exists at all: max_turns is a cost and runaway-loop protection, not a feature limit.

The code to have ready

You should be able to write these from memory on a shared editor without looking anything up. They are short, and fumbling them is the easiest avoidable loss in a technical screen.

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")
result = await Runner.run(agent, "Hello")
print(result.final_output)

from agents.decorators import tool

@tool
def get_weather(city: str) -> str:
    """Return weather info for the specified city."""
    return f"The weather in {city} is sunny"

from pydantic import BaseModel

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

agent = Agent(name="Extractor", instructions="Extract calendar events", output_type=CalendarEvent)

from agents import SQLiteSession

session = SQLiteSession("user_123", "conversations.db")
result = await Runner.run(agent, "And what state is it in?", session=session)

Four facts you should be able to state alongside them, because interviewers ask "and what does that actually do?":

• The package is openai-agents, the import is agents, and Python 3.10 or newer is required.
• @tool lives in agents.decorators and is an alias of @function_tool, added in 0.19.0. Both work; the current docs use @tool.
• output_type makes result.final_output an instance of that Pydantic model, validated before you see it.
• A session loads history before each run and saves the new items after it. SQLiteSession with no filename is in-memory; with a filename it is a real file.

The classic traps, and why they happen

Interviewers like traps because a candidate's explanation of why a trap exists tells them more than whether the candidate has hit it.

run_sync inside a running event loop. The error is AgentRunner.run_sync() cannot be called when an event loop is already running. It happens in Jupyter, in FastAPI handlers, in bot callbacks — anywhere inside async def. The cause is that run_sync works by starting an event loop, and you cannot start one inside one. The fix is await Runner.run(...). Say the cause, not just the fix.

MaxTurnsExceeded treated as a limit to raise. Ten model calls for one question nearly always means the agent is going in circles: a tool whose output the model does not understand, instructions that demand repeated verification, or a forced tool_choice="required" with the loop protection turned off. The strong answer is "I'd read the trace and count what it actually did before touching max_turns." The weak answer is "set it to 50."

Expecting tool exceptions to fail the run. By default a raising tool does not crash the run: the SDK catches it and gives the model the text "An error occurred while running the tool. Please try again.", and the loop continues. Passing failure_error_function=None explicitly re-raises instead. So omitting the argument and passing None are different behaviours, which is genuinely surprising and a good thing to know.

Thinking a docstring is documentation. The docstring is the only description of the tool the model receives, and the type hints are the only constraint on its arguments. When a model calls a tool with nonsense, the first fix is the docstring and the hints, not the instructions.

Assuming output_type on the first agent covers every route. final_output comes from whichever agent finished, so after a handoff the specialist's output_type (or lack of one) is what applies. If every route must return the same shape, set output_type on every agent that can finish.

Confusing local context with what the model sees. The object you pass as Runner.run(..., context=obj) is never sent to the LLM. Tools read it at ctx.context. The model's context is a different thing: instructions, the input and history, and tool results. Candidates who blur these two usually also propose putting a database handle in the prompt.

Breaking out of stream_events() early. Session writes and history compaction happen after the last token, so abandoning the stream once you have the text can lose the history you believed you were saving. Drain the iterator.

Assuming there are retries. The SDK does not retry model calls unless you set ModelSettings.retry. There is no silent retry layer.

Common interview questions, with model answers

"What is a turn, and why does max_turns default to 10?" A turn is one model call inside the agent loop, not one user message. An agent that calls two tools before answering uses three turns. The default of 10 exists because every turn is a billable model call, so a tool-call loop without a limit would run and charge indefinitely; the limit converts a runaway loop into a MaxTurnsExceeded exception you can catch. You can raise it, and since 0.16.0 you can pass None to disable it, which is only safe if something else bounds the loop.

"When would you use a handoff rather than as_tool?" When the specialist should own the rest of the conversation. A support triage agent that routes a refund request to a refunds agent wants a handoff: history and control move across, and result.last_agent is the refunds agent. If instead one agent must write the final answer and the others only contribute — a report writer that consults a summariser and a fact-checker — use as_tool, because the orchestrator keeps control and simply receives results. The deciding question is who is talking to the user at the end.

"How do you make an agent return something your code can use?" Set output_type to a Pydantic model. The SDK turns it into a JSON schema, constrains the model's output to it, and validates before returning, so result.final_output is an instance of that model with the declared types. That is a real guarantee, unlike asking the model to "reply in JSON". The constraint is that strict schemas need a non-nullable object at the root, so a dict[str, Any] or a top-level Union is rejected — wrap it in a model with named fields, which is better design anyway.

"How does the model know what your function does?" From the decorator. @tool takes the tool name from the function name, the description from the docstring — parsed with griffe — and the JSON schema for the arguments from the type hints via Pydantic. That is why docstrings and hints are functional code here rather than documentation. You can override the name and description with name_override and description_override if you need to.

"Where does conversation history live?" Wherever you put it, because the SDK is a library with no state of its own. Three options: do it by hand with result.to_input_list() plus the next user message; use a session such as SQLiteSession, which loads history before each run and saves it afterwards; or use server-managed state with conversation_id or previous_response_id. You pick one per call — combining a session with server-managed state raises UserError. SQLiteSession is for development; production uses Redis, SQLAlchemy over Postgres, MongoDB or the Conversations API.

"How would you stop an agent answering a question it should not?" An input guardrail: a function that inspects the input and returns GuardrailFunctionOutput with tripwire_triggered=True, which raises InputGuardrailTripwireTriggered and stops the run. Two details matter. Input guardrails run only on the first agent of a run, and output guardrails only on the agent producing the final output. And by default input guardrails run in parallel with the agent, so a tripped guardrail may fire after tokens were already spent — @input_guardrail(run_in_parallel=False) makes it block first, which is what you want when cost or side effects matter. I would also add that a guardrail is a content filter, not authorisation; real permission checks go inside the tool.

"Your agent calls the same tool over and over. What do you do?" Open the trace first. The spans show the exact arguments the model generated and what the tool returned, and the usual cause is visible immediately: the tool returned something the model could not use, so it tried again. The fixes, in order, are a clearer tool docstring and return value, then tighter instructions about when the tool is done, then checking whether tool_choice="required" is forcing a call every turn. Raising max_turns is the last resort, not the first.

"How do you debug an agent at all?" Tracing is on by default and exports to the OpenAI Traces dashboard, with spans for the agent, each generation, each function call, each guardrail and each handoff. I set workflow_name so traces are findable and group_id to the conversation ID so one thread's runs group together. For deeper problems, enable_verbose_stdout_logging() prints the traffic, and because model and tool payloads are redacted by default I temporarily set OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0 in development to see the real arguments. I would not do that in production, since those payloads contain user data.

"Which model does it use if you don't say?" The SDK default, which is currently gpt-5.6-luna — it changed in 0.20.0 from gpt-5.4-mini, and before that from gpt-4.1. Precedence is the agent's explicit model, then RunConfig.model, then the OPENAI_DEFAULT_MODEL environment variable, then the SDK default. Because that default has moved twice recently, I set the model explicitly in anything deployed, and I pin the SDK to the 0.22 series with openai-agents~=0.22.3, since minor versions can break public APIs by design.

What a strong answer has that a weak one does not

A weak answer describes features. A strong answer describes behaviour, cost and failure.

Weak: "You create an agent and give it tools and it uses them." Strong: "You create an agent and the model decides which tool to call; the runner executes it, appends the result and calls the model again, so one question can be several turns and several bills."

Weak: "You set max_turns higher if it runs out." Strong: "Running out of turns is usually a loop, so I read the trace first."

Weak: "Guardrails make it safe." Strong: "Guardrails filter content; authorisation goes in the tool, because tool arguments come from the model and are untrusted."

Weak: "It remembers the conversation." Strong: "It remembers nothing unless I give it a session or pass the history myself, and the session ID is not authentication."

Sixty-second self-test

Answer out loud, without notes. Any hesitation marks the section to re-read.

1. What is a turn, and what is the default max_turns?
2. What are the two conditions for an output to count as final?
3. Where does @tool get the tool's name, description and argument schema?
4. Name the difference between a handoff and as_tool in one sentence.
5. Why does Runner.run_sync fail in a FastAPI handler?
6. Is the object you pass as context= sent to the model?
7. Which agent do input guardrails run on? Which do output guardrails run on?
8. What does result.final_output contain when output_type is set, and when it is not?
9. Name two reasons MaxTurnsExceeded happens.
10. What is the install name of the package, and the import name?
11. What happens by default when a function tool raises an exception?
12. Why should you set the model explicitly instead of relying on the default?

The answers, compressed: one model call and 10; text of the desired type and no tool calls; the function name, the docstring and the type hints; a handoff gives control to the specialist while as_tool keeps it with the caller; because run_sync starts an event loop and one is already running; no, never; the first agent, and the agent producing the final output; an instance of the output_type or a str; a tool-call loop or instructions that demand repeated work; openai-agents and agents; the SDK catches it and tells the model an error occurred, and the loop continues; because the SDK default model has changed across minor versions and would change your latency and cost without a code change.

This is the third part of the Beginner level: the mistakes people actually make with the OpenAI Agents SDK in their first week, the habits that prevent most of them, and a checklist to run before you show your agent to anybody. It is written to be read once now and skimmed again the first time something breaks.

The pattern you will notice is that very few beginner problems with this SDK are about the SDK. They are about forgetting that the model is making the decisions, that every decision costs a model call, and that the only description your tools have is the one you wrote in a docstring.

The mistakes beginners actually make

Calling run_sync inside something async

Symptom. AgentRunner.run_sync() cannot be called when an event loop is already running.

Cause. Runner.run_sync works by starting an event loop and running the async code inside it. If a loop is already running — a Jupyter cell, a FastAPI route, a Telegram or Discord bot callback, anything inside async def — there is no loop for it to start.

Fix. await Runner.run(...). In a notebook, await works at the top level of a cell, so you do not even need asyncio.run. Treat run_sync as a convenience for standalone scripts and tests only; if you are writing a service, you will never use it.

Installing the wrong name

Symptom. ModuleNotFoundError: No module named 'agents', or an import error about openai.

Cause. Two separate versions of this. Either you installed something other than openai-agents (the package is openai-agents, the import is agents), or you installed into one Python and are running another — almost always a forgotten source .venv/bin/activate.

Fix. Create a virtual environment, install openai-agents into it, and verify with python -c "import agents, importlib.metadata as m; print(m.version('openai-agents'))". The SDK pins its dependencies tightly — openai 3.x and pydantic 2.x at 0.22.3 — so installing it next to an older openai in a system Python is an efficient way to waste an afternoon.

Treating MaxTurnsExceeded as a limit to raise

Symptom. MaxTurnsExceeded: Max turns (10) exceeded, and the instinct to pass max_turns=50.

Cause. Ten model calls for one question means the agent is going in circles. The usual reasons are a tool that returns something the model cannot act on, so it calls it again; instructions that tell it to double-check everything; or tool_choice="required" forcing a tool call on every turn.

Fix. Read the trace and count what it actually did before changing anything. Then fix the tool's return value or the instructions. Raising the limit without understanding the loop just makes the same bug cost five times as much.

Writing a tool with no docstring or no type hints

Symptom. The model ignores the tool, or calls it with values that make no sense.

Cause. The @tool decorator takes the tool's name from the function name, its description from the docstring, and its argument schema from the type hints. A missing docstring means the model has no idea what the tool is for. A missing hint means the schema does not constrain the argument.

Fix. One clear sentence per tool, and a type hint on every parameter. Say what the parameter means, not just what it is: order_id: str with a docstring reading "Look up the delivery status of one order by its ID" is dramatically better than get_status(x).

Expecting a raising tool to fail the run

Symptom. Your database call fails, nothing is logged loudly, and the agent cheerfully tells the user something made up.

Cause. By default the SDK catches exceptions in a function tool and returns "An error occurred while running the tool. Please try again." to the model, then keeps looping. That is a sensible default for flaky tools and a terrible one for tools whose failure should fail the request.

Fix. Pass failure_error_function=None explicitly on the tools where a failure must stop everything — note that omitting the argument and passing None are different behaviours. Or catch the error inside the tool and return a message the model can act on, such as "No order found with that ID.", which is usually the better answer for user-facing lookups.

Returning everything from a tool

Symptom. Costs are high, latency is poor, and the agent's answers wander.

Cause. A tool that returns a whole API response puts all of it into the model's context, every turn thereafter. Five such calls and your prompt is enormous.

Fix. Return the smallest thing that answers the question. If the model needs three fields, return three fields. This is the single highest-leverage cost optimisation available to a beginner and it costs nothing to do.

Putting secrets or whole objects in the prompt

Symptom. A database handle stringified into instructions, or an API key visible in a trace.

Cause. Not knowing that there is a proper channel for this. The object you pass as Runner.run(..., context=obj) is never sent to the LLM; tools and hooks receive it as RunContextWrapper[T] and read it at .context.

Fix. Put the user ID, the tenant, the database handle and anything else your tools need into a small dataclass and pass it as context=. Keep it out of instructions entirely. One caveat for later: context is serialised if you ever persist a run's state, so secrets do not belong there either — load those from your secret manager inside the tool.

Trusting the session ID from the request

Symptom. In code review: session = SQLiteSession(request.json["session_id"]).

Cause. A session ID looks like an identifier, so it feels like identity.

Cause and fix, plainly. A session ID is not authentication. Anyone who guesses or replays one reads somebody else's conversation. Authenticate the user first, then derive the session ID from the authenticated identity — SQLiteSession(f"support:{user.id}"). This matters more than usual if you work under a data-protection regime such as Saudi Arabia's PDPL or Egypt's data protection law, where a conversation log is personal data and a leak is a reportable event.

Breaking out of the stream early

Symptom. The answer displays fine, but the conversation history is missing the last exchange; or the stream appears to hang for a second after the final word.

Cause. Session writes, approval bookkeeping and history compaction run after the last token. If you break out of stream_events() as soon as you have the text, that work never happens.

Fix. Always drain the iterator to completion. The apparent hang is the post-processing, not a bug.

Relying on the default model

Symptom. A routine dependency upgrade changes your latency, your output style and your bill, with no code change.

Cause. If you do not set a model, the SDK uses its default. That default is currently gpt-5.6-luna, and it changed in 0.20.0 from gpt-5.4-mini, which had itself replaced gpt-4.1.

Fix. Set model= explicitly on every agent you deploy, and pin the SDK to the 0.22 series with openai-agents~=0.22.3. The minor version number goes up for breaking changes by design, so an unpinned install is an unpinned API.

Setting output_type on only the first agent

Symptom. Your code does result.final_output.answer and gets an AttributeError on a string, but only sometimes.

Cause. final_output comes from whichever agent finished the run. After a handoff, that is the specialist, and if the specialist has no output_type you get plain text.

Fix. Set output_type on every agent that can finish a run, not just the entry point.

Using dict as an output type

Symptom. UserError: The root of a strict JSON schema must be a non-nullable object..., or a complaint about anyOf.

Cause. Strict schemas are the default, and they require a non-nullable object at the root. A dict[str, Any], a bare list, or a top-level Union cannot be expressed.

Fix. Wrap it in a Pydantic model with named fields. class Result(BaseModel): items: list[Item] works and is better design than a free-form dict, because now the model knows what you want.

Confusing the two kinds of context

Symptom. A code review question you cannot answer: "wait, does the model see that?"

Cause. The word "context" is used for two different things in this SDK and they have opposite properties. Local context is the Python object you pass as context=; it is for your code and is never transmitted. Agent context, or LLM context, is what the model actually sees: the instructions, the input and history, the tool results, and anything retrieved by a search tool.

Fix. Say which one you mean, every time. When you are deciding where something belongs, ask whether the model needs to reason about it. A customer's order history: yes, so it goes into a tool result. The database connection string used to fetch it: no, so it goes into local context. One further rule the SDK enforces: every agent and tool in a single run must use the same local context type, so design that dataclass once for the whole run rather than per agent.

Combining a session with server-managed state

Symptom. UserError: Session persistence cannot be combined with conversation_id, previous_response_id, or auto_previous_response_id.

Cause. There are two complete strategies for conversation history and you reached for both. A local session stores the items on your side; conversation_id and previous_response_id ask OpenAI to keep them. Having both would mean the history is replayed twice.

Fix. Pick one per call. Local sessions are the better default for a beginner because you can open the SQLite file and read exactly what the model was shown, and because the history stays on infrastructure you control — which matters if you are working under a data-residency requirement. There is a related restriction worth knowing before you hit it: output guardrails also cannot be combined with server-managed state, because a rejected output cannot be removed from a conversation OpenAI owns.

Forgetting to await, or awaiting the wrong thing

Symptom. A coroutine warning and no output, or an unhelpful TypeError on a result object.

Cause. Two opposite slips. Runner.run is async and must be awaited. Runner.run_streamed is not awaited — it returns a result object immediately and the work happens as you iterate stream_events().

Fix. Remember the shapes: result = await Runner.run(...) and result = Runner.run_streamed(...) followed by async for event in result.stream_events():. If Python warns that a coroutine was never awaited, you missed an await; if an object does not behave like a result, you added one.

Using a deprecated entry point from an old tutorial

Symptom. Code works but warns, or uses an API the current docs no longer mention.

Cause. The SDK has moved quickly and search results have not caught up. A few specifics to recognise: MCPServerSse is legacy because the MCP project deprecated the SSE transport, so new work uses MCPServerStreamableHttp or MCPServerStdio; LocalShellTool is a legacy local-shell integration superseded by ShellTool; and nested handoff history has been opt-in and off by default since 0.7.0, so a tutorial that relies on it being on is describing old behaviour.

Fix. When something you copied disagrees with the official docs, the docs win, and check the release notes for the version you are pinned to. One exception that looks like a mistake and is not: the streamed event name handoff_occured is misspelled deliberately and preserved for backward compatibility. Do not correct it — the corrected spelling does not exist.

Habits worth adopting on day one

Open the trace before changing the prompt. Tracing is on by default and every run you have made is already at the Traces dashboard, with spans for the agent, each model generation, each function call, each guardrail and each handoff. The function span shows the exact arguments the model invented. Most "the agent is broken" reports are really "the model passed a value my tool did not expect", and the trace shows that in one glance. Prompt surgery performed without reading the trace is guessing.

Name your workflows and group your runs. RunConfig(workflow_name="Support triage", group_id=thread_id) costs one line and turns a hundred identical traces called "Agent workflow" into something navigable. Use the conversation or thread ID as the group.

Print the token count while you are learning. result.context_wrapper.usage gives you requests, input_tokens, output_tokens and total_tokens. Logging total_tokens after each run for your first week builds an instinct for what things cost that no amount of reading provides. You will discover quickly that adding a chatty brief and two more tools can multiply a request's cost several times over.

Write the instructions like a brief for a new colleague. Say what the agent is for, what it must refuse, what format you want, and which tool to prefer in which situation. "You are a helpful assistant" is a demo. Four specific sentences is a brief, and it is usually worth more than switching to a bigger model.

Set a timeout. ModelSettings(timeout=30.0) limits each model attempt and raises ModelTimeoutError. The default is no timeout at all, so a hung model call hangs your request indefinitely. Thirty seconds is a fine starting number.

Prefer several small agents to one large one. An agent with twenty tools and a two-page brief chooses badly. Three agents with clear jobs and good handoff_description values route well. And remember that the handoff description is the only text the router sees about each route — vague descriptions, not bad router prompts, are the usual cause of bad routing.

Keep authorisation inside the tool. Tool arguments are generated by the model and are untrusted input. is_enabled controls what the model sees, not what your code is allowed to do. Check the authenticated user from ctx.context inside the tool and refuse there.

Leave the default log redaction on. Setting OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0 to see what the model really sent is a good debugging move in development and a data-protection incident in production.

The checklist

Run this before you show an agent to a colleague, and again before anything resembling production.

Setup

• A virtual environment, with openai-agents installed and the version printed and recorded.
• The SDK pinned to one minor series, e.g. openai-agents~=0.22.3, in your requirements.
• OPENAI_API_KEY loaded from the environment or a secret manager, never from code.

Each agent

• model set explicitly, not inherited from the SDK default.
• instructions that say what it is for, what it refuses, what format to use, and which tool to prefer.
• output_type set on every agent that can finish the run, if your code expects a structured answer.
• model_settings with at least a timeout.

Each tool

• A descriptive name, a one-sentence docstring, and type hints on every parameter.
• Returns the smallest useful result, not a whole API response.
• Handles its own expected failures with a message the model can act on.
• failure_error_function=None where a failure must stop the run.
• Authorisation checked inside the function, against ctx.context.

Conversation and safety

• One history strategy per call: a session, or server-managed state, never both.
• Session IDs derived from the authenticated user, never taken from request input.
• SQLiteSession only in development; a real backend for anything shared.
• An input guardrail on the first agent for anything you must refuse, in blocking mode if cost matters.
• Secrets kept out of both instructions and context.

Operating it

• workflow_name and group_id set on every run.
• total_tokens logged per run.
• MaxTurnsExceeded and the tripwire exceptions caught where you call the agent, with a sensible user-facing message.
• Default log redaction left on.
• A decision made, deliberately, about whether prompt contents may be exported to a tracing dashboard — and a third-party processor such as Langfuse or MLflow if they may not, or if your organisation is on Zero Data Retention and OpenAI tracing is unavailable to you.

If every line of that passes, you have an agent that behaves predictably, costs what you expect, fails visibly and can be debugged by somebody who did not write it. That is the whole goal of the beginner level, and it is a better position than most agent code currently running in production.

This is part two of three. Beginner gave you an Agent, a Runner, a few function tools and a session. This level takes each of those apart far enough that you can predict what the SDK will do before you run it, and then adds the machinery a service needs: guardrails that actually hold, sessions that survive a restart, MCP servers that do not add a round trip to every request, retries and timeouts, tracing, and tests that do not call a model.

Where this picks up

Everything here is verified against openai-agents 0.22.3 on Python 3.10 or newer. The package is openai-agents; you import it as agents. Pin it as openai-agents~=0.22.3 or >=0.22,<0.23, because the SDK uses the minor number for breaking changes to public, non-beta APIs.

Each section opens with the problem it solves and ends with a Try it you can run against a real project in a few minutes.

The agent loop, step by step

Beginner described the loop as "the model calls tools until it answers". That is true, and it is not precise enough to debug a run that costs ten model calls when you expected two. The loop has exactly four outcomes per turn.

A turn is one model call. It is not one user message, and this is the single most common misreading of the SDK. One Runner.run with a chatty tool-using agent can burn eight turns on one user sentence.

Per iteration the runner does this:

1. Calls the LLM for the current agent with the current input.
2. If the output is final — text matching the desired output_type, and no tool calls — the run returns.
3. If the output is a handoff, the current agent changes and the loop continues.
4. If there are tool calls, it runs them, appends the results as items, and loops.
5. If the iteration count passes max_turns, it raises MaxTurnsExceeded.

Read step 2 twice. "No tool calls" is part of the definition of final. A model that emits a perfectly good answer and a redundant tool call in the same response does not end the run; you pay for another turn. max_turns defaults to 10 (DEFAULT_MAX_TURNS = 10), and passing max_turns=None disables the limit entirely — useful for a batch job you babysit, dangerous for a request handler.

Runner has three entry points. Runner.run is async and the one you want in a service. Runner.run_sync is a thin wrapper that refuses to work when a loop is already running, which is why AgentRunner.run_sync() cannot be called when an event loop is already running. is the first error most people hit in a notebook or a FastAPI handler. Runner.run_streamed is async but not awaited — it returns a streaming result object immediately.

The full signature at 0.22.3:

result = await Runner.run(
    starting_agent,
    input,                      # str | list[TResponseInputItem] | RunState
    context=None,
    max_turns=10,
    hooks=None,
    run_config=None,
    error_handlers=None,
    previous_response_id=None,
    auto_previous_response_id=False,
    conversation_id=None,
    session=None,
)

RunConfig is where run-wide policy lives, and it is worth knowing by heart because almost every production control is one of its fields: model and model_provider and model_settings for model policy; input_guardrails and output_guardrails to add guardrails to a whole run rather than one agent; tracing_disabled, workflow_name, group_id, trace_metadata and trace_include_sensitive_data for observability; session_settings, session_input_callback and call_model_input_filter for context control; tool_execution, tool_not_found_behavior and tool_name_collision_policy for tool policy. Anywhere a RunConfig is accepted a plain dict works too — and since 0.19 an unknown key in that dict raises TypeError instead of being silently ignored, which is a feature, not an annoyance.

Two tool-policy defaults deserve a decision rather than inheritance. tool_not_found_behavior defaults to "raise_error", so a hallucinated tool name kills the run with ModelBehaviorError; "return_error_to_model" instead hands the model the text Tool '<name>' not found. and lets it recover, which is usually what a user-facing agent should do. tool_name_collision_policy defaults to "warn", which means two tools with the same name — easy to arrange once you mix MCP servers and local tools — produce a log line and an ambiguous agent. Set it to "error" in CI.

from agents import RunConfig, Runner

result = await Runner.run(
    triage_agent,
    user_text,
    max_turns=6,
    run_config=RunConfig(
        workflow_name="support-triage",
        group_id=thread_id,
        tool_not_found_behavior="return_error_to_model",
        tool_name_collision_policy="error",
    ),
)

Reading the result object

A run returns more than a string, and the extra fields are what you log, store and assert on.

result.final_output is a str when the last agent has no output_type, and an instance of last_agent.output_type otherwise. It is typed Any for a good reason: a handoff can change which agent finishes the run, so the static type of the result cannot be known. It is None when the run paused — for example on a tool approval — and code that assumes a non-None final output will fail the first time someone adds needs_approval=True to a tool.

result.last_agent is the agent that produced the final output. After a handoff it is the specialist, not the agent you started with. Persist its name if you want the next turn of a conversation to continue with the same specialist.

result.to_input_list() gives you the full input plus everything generated, ready to be the input of the next run — this is manual multi-turn chat, and it is what a session automates. result.to_state() serialises the run into a RunState you can store and resume; since 0.22.0 each checkpoint owns an independent usage snapshot, so two states taken from the same run no longer share usage counters. result.interruptions holds pending approvals. result.last_response_id is what you chain into previous_response_id.

result.context_wrapper.usage is the cost record: requests, input_tokens, output_tokens, total_tokens, request_usage_entries, plus input_tokens_details.cached_tokens and cache_write_tokens, and output_tokens_details.reasoning_tokens. Log all of it. The cached-token field is the only way to tell whether your prompt caching is working, and the reasoning-token field is the only way to see that an effort setting you thought was off is not.

u = result.context_wrapper.usage
log.info(
    "run complete agent=%s turns=%d in=%d out=%d cached=%d reasoning=%d",
    result.last_agent.name,
    u.requests,
    u.input_tokens,
    u.output_tokens,
    u.input_tokens_details.cached_tokens,
    u.output_tokens_details.reasoning_tokens,
)

Two kinds of context, and which one the model sees

The word "context" means two different things in this SDK, and conflating them produces both security bugs and confusing model behaviour.

Local context is any Python object you pass as Runner.run(..., context=obj). Tools, hooks, guardrails and callbacks receive it wrapped as RunContextWrapper[T] and read it at .context. It is never sent to the LLM. It is the right home for the authenticated user ID, the tenant, a database handle, a request-scoped logger, feature flags. Every agent and tool in one run must use the same context type, which is why Agent[UserContext] is a generic.

Agent context, or LLM context, is what the model actually sees: the instructions, the input and history, tool results, and retrieval or search output. If you want the model to know the user's name, it has to reach the model through one of those channels — most cleanly through dynamic instructions.

from dataclasses import dataclass
from agents import Agent, RunContextWrapper, Runner

@dataclass
class UserContext:
    user_id: str
    name: str
    tenant: str

def instructions(ctx: RunContextWrapper[UserContext], agent: Agent[UserContext]) -> str:
    return f"You are helping {ctx.context.name}. Keep answers under 120 words."

agent = Agent[UserContext](name="Support", instructions=instructions)
result = await Runner.run(agent, "where is my order", context=UserContext("u_1", "Aya", "acme"))

instructions can be a string, a sync callable, or an async callable taking (ctx, agent). The callable form is how you inject per-tenant policy, locale, or the current date without rebuilding agents.

The wrapper carries more than .context: .usage is the live usage for the run, .tool_input is the generated input when the agent is running as a tool, and .approve_tool() / .reject_tool() let a hook decide an approval programmatically. Tool functions that need identifying information about the specific call receive a ToolContext instead, which adds tool_call_id, tool_name and tool_arguments.

There is one rule to internalise, and it has bitten teams that persist paused runs: local context is not sent to the model, but it is serialised into RunState. If you call result.to_state() and write the JSON to a database, everything in your context goes with it. Keep database handles and API keys out of context when you persist state, or pass a context_serializer that drops them.

Function tools in depth

Beginner showed @tool on a function. The decorator has about a dozen parameters, and in production most of them matter.

The tool's name comes from the function name, its description from the docstring — parsed with griffe, so your docstring style is honoured — and its JSON schema from the signature via Pydantic. That means your type hints are an API contract the model reads. str, int, enums and Pydantic models produce schemas a model can satisfy; dict[str, Any] produces a schema that invites garbage.

from typing import Literal
from pydantic import BaseModel
from agents.decorators import tool

class Shipment(BaseModel):
    order_id: str
    status: Literal["pending", "shipped", "delivered"]
    eta_days: int

@tool(timeout=5.0, timeout_behavior="error_as_result")
async def lookup_shipment(order_id: str) -> Shipment:
    """Look up the shipment status for one order.

    Args:
        order_id: The order reference, e.g. ORD-10431.
    """
    row = await db.fetch_one("select * from shipments where id = $1", order_id)
    return Shipment(order_id=order_id, status=row["status"], eta_days=row["eta"])

The parameters worth knowing, with their 0.22.3 defaults:

Three of these change behaviour in ways that surprise people.

strict_mode is True by default. Documentation summaries sometimes claim otherwise; the source does not. Strict mode is why a tool taking a free-form dict fails at agent construction with UserError: The root of a strict JSON schema must be a non-nullable object.... The fix is to model the input, not to disable the check.

failure_error_function has three states, not two. Leave it out and a raising tool returns the text "An error occurred while running the tool. Please try again." to the model, which keeps looping. Pass your own function to return a better message. Pass None explicitly and the exception propagates and kills the run. For a tool that charges money or mutates data, failing fast is usually right; for a flaky read, returning an error to the model is right.

Timeouts only work on async tools. @tool(timeout=2.0) on a sync function does nothing. With the default timeout_behavior="error_as_result" the model is told the tool timed out and can try something else; with "raise_exception" you get ToolTimeoutError: Tool 'slow_lookup' timed out after 2 seconds., carrying .tool_name and .timeout_seconds.

Sync tools have run in worker threads since 0.8.0, so a blocking requests call will not stall the event loop — but it does occupy a thread, and the runner starts local tools for one turn concurrently and unbounded unless you cap it:

from agents import RunConfig
from agents.run import ToolExecutionConfig

run_config = RunConfig(tool_execution=ToolExecutionConfig(max_function_tool_concurrency=4))

That cap is not the same lever as ModelSettings(parallel_tool_calls=...). The model setting decides whether the model emits parallel calls at all; the execution config decides how many of the ones it emitted you run at once. A tool that hits a database with a ten-connection pool needs the second.

tool_use_behavior on the agent decides what happens to tool output. The default "run_llm_again" sends results back for another turn. "stop_on_first_tool" makes the first tool's output the final output, which turns an agent into a one-shot classifier-and-dispatch with exactly one model call. StopAtTools(stop_at_tool_names=[...]), imported from agents.agent, stops only on named tools. A custom function (ctx, list[FunctionToolResult]) -> ToolsToFinalOutputResult(...) covers the rest.

Finally, tool.__wrapped__ exposes the original callable so unit tests can call the plain function — bypassing validation, guardrails and tracing, which is exactly what you want for testing business logic and exactly what you must not use when testing the guardrails themselves.

Handoffs versus agents as tools

Both are multi-agent delegation. They differ in who owns the conversation afterwards, and choosing wrongly is the most common structural mistake at this level.

A handoff transfers control. The model sees it as a tool named transfer_to_<agent_name>, the specialist takes over the conversation, and result.last_agent is the specialist. Handoffs stay inside one run.

An agent as tool keeps control. agent.as_tool(tool_name=..., tool_description=...) makes the specialist a callable; the orchestrator gets the result back and writes the final answer itself. Since 0.9.0 as_tool() returns a FunctionTool.

The history rule is the part people get wrong. A nested as-tool run does not inherit the parent's conversation unless you pass the same session. That isolation is usually a feature: a summariser does not need the whole support thread, and not sending it is cheaper. But it means "the sub-agent did not know what the user said earlier" is expected behaviour, not a bug.

handoff() gives you the controls a bare agent reference does not:

from agents import Agent, handoff
from agents.extensions import handoff_filters
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
from pydantic import BaseModel

class EscalationData(BaseModel):
    reason: str
    priority: int

async def on_escalate(ctx, input_data: EscalationData) -> None:
    if not ctx.context.may_escalate:
        raise PermissionError("tenant not allowed to escalate")
    await audit.record(ctx.context.user_id, input_data.reason)

billing = Agent(name="Billing", handoff_description="Invoices, refunds, payment failures",
                instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nResolve billing questions.")

triage = Agent(
    name="Triage",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nRoute each request to one specialist.",
    handoffs=[
        handoff(billing,
                tool_description_override="Use for anything about money.",
                input_type=EscalationData,
                on_handoff=on_escalate,
                input_filter=handoff_filters.remove_all_tools),
    ],
)

input_type makes the model produce structured metadata with the handoff — a reason, a priority. It does not replace the next agent's input. on_handoff is your authorisation and audit hook, and raising inside it is the correct way to refuse a handoff the model chose but the tenant is not allowed. input_filter rewrites HandoffInputData (fields input_history, pre_handoff_items, new_items, input_items, run_context) before the specialist sees it; handoff_filters.remove_all_tools is the ready-made one that strips tool chatter.

Two constraints to write on the wall. Nested handoff history has been opt-in since 0.7.0 — nest_handoff_history on the handoff or RunConfig, still beta — so do not teach or assume the old default. And server-managed conversations do not support handoff input filters: if you are using conversation_id, your filter is not running.

Guardrails that hold in production

A guardrail is a function returning GuardrailFunctionOutput(output_info=..., tripwire_triggered=bool). A True tripwire raises and stops the run. There are three kinds, and each runs in exactly one place:

• Input guardrails run only on the first agent of a run.
• Output guardrails run only on the agent that produces the final output.
• Tool guardrails run on every call of a guarded function tool.

That placement is the whole design, and it explains the usual disappointment: an input guardrail on your triage agent does not re-run after a handoff, so a specialist reached by handoff is not re-screened. If you need screening everywhere, put the guardrails on RunConfig or inside the tools.

from agents import Agent, GuardrailFunctionOutput, InputGuardrailTripwireTriggered, Runner
from agents.decorators import input_guardrail

@input_guardrail(run_in_parallel=False)
async def off_topic(ctx, agent, input) -> GuardrailFunctionOutput:
    verdict = await Runner.run(classifier_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(output_info=verdict.final_output,
                                   tripwire_triggered=verdict.final_output.is_off_topic)

support = Agent(name="Support", instructions="...", input_guardrails=[off_topic])

try:
    result = await Runner.run(support, user_text)
except InputGuardrailTripwireTriggered as e:
    log.warning("blocked: %s", e.guardrail_result)
    return "I can only help with orders and billing."

Input guardrails run in parallel with the agent by default. Latency is lower, and the price is that the main agent may already have spent tokens and run tools before the tripwire cancels it. run_in_parallel=False makes the guardrail run first and block. Use blocking mode whenever the agent's tools have side effects or when tokens are the thing you are trying to save; use parallel mode for a latency-sensitive read-only assistant. Output guardrails have no such option — they always run after the agent finishes.

Tool guardrails are the finer-grained control, and the only one that can modify rather than only stop:

import json
from agents import ToolGuardrailFunctionOutput
from agents.decorators import tool, tool_input_guardrail

@tool_input_guardrail
def block_secrets(data):
    args = json.loads(data.context.tool_arguments or "{}")
    if "sk-" in json.dumps(args):
        return ToolGuardrailFunctionOutput.reject_content("Remove secrets before calling this tool.")
    return ToolGuardrailFunctionOutput.allow()

@tool(tool_input_guardrails=[block_secrets])
def classify_text(text: str) -> str:
    ...

reject_content(...) replaces the content and lets the run continue, which is what you want for a recoverable policy violation. A tripwire instead raises ToolInputGuardrailTripwireTriggered or ToolOutputGuardrailTripwireTriggered.

One combination raises UserError outright: output guardrails cannot be used with conversation_id, previous_response_id or auto_previous_response_id on the Responses path, because rejected output cannot be removed from server-managed history. If you need output guardrails, keep history locally with a session or to_input_list(). Relatedly, since 0.22.0, when an output guardrail blocks a final output that a terminal function tool produced directly, the stored function_call_output is replaced with the fixed text "Output withheld by an output guardrail."; RunConfig.output_guardrail_blocked_message customises it with a string or a sync formatter.

Sessions and conversation state

There are three mutually exclusive ways to carry a conversation forward, and the SDK enforces the exclusivity.

Manual is new_input = result.to_input_list() + [{"role": "user", "content": "..."}]. Full control, no dependencies, and you own trimming.

Sessions load history before each run and save new items after it. SQLiteSession("thread_1") is in-memory, SQLiteSession("thread_1", "conversations.db") is file-backed — development only, both of them. Production backends live in agents.extensions.memory: RedisSession.from_url(...), SQLAlchemySession.from_url(..., create_tables=True) for Postgres, MongoDBSession.from_uri(...), DaprSession.from_address(...), AsyncSQLiteSession (needs pip install aiosqlite), AdvancedSQLiteSession, and EncryptedSession(session_id=, underlying_session=, encryption_key=, ttl=). Install what you need as an extra: pip install "openai-agents[redis,sqlalchemy]".

Server-managed state keeps history at OpenAI, either as a conversation or as a response chain:

from openai import AsyncOpenAI
from agents import Runner

conv = await AsyncOpenAI().conversations.create()
await Runner.run(agent, user_input, conversation_id=conv.id)

# or chain responses instead
result = await Runner.run(agent, user_input, previous_response_id=prev, auto_previous_response_id=True)
prev = result.last_response_id

The rules: conversation_id and previous_response_id cannot be used together, and neither can be combined with session — UserError: Session persistence cannot be combined with conversation_id, previous_response_id, or auto_previous_response_id. Pick one strategy per call and make it explicit in your service layer rather than per-handler.

Session objects expose get_items(limit=None), add_items(items), pop_item() and clear_session(). pop_item() is the clean way to implement "edit my last message": pop the assistant item, pop the user item, re-run. A custom backend only has to implement the Session protocol structurally — subclassing SessionABC is not required — and may accept a wrapper keyword to receive the RunContextWrapper, which is how you route a session to a per-tenant database.

History growth is the operational problem sessions create. Four levers, roughly in order of how often they are the right one:

from agents import RunConfig
from agents.run import SessionSettings

run_config = RunConfig(session_settings=SessionSettings(limit=50))   # retrieve the last 50 items

def merge(history, new_input):                                        # custom merge
    return history[-20:] + new_input

run_config = RunConfig(session_input_callback=merge)

Beyond those, ModelSettings(truncation="auto") lets the server drop the middle, server-side context_management=[{"type": "compaction", "compact_threshold": N}] compacts at the API, and OpenAIResponsesCompactionSession(session_id=, underlying_session=, should_trigger_compaction=, compaction_mode=...) from agents.memory wraps another session with automatic compaction. A session_input_callback that returns anything other than a list raises UserError: Session input callback must return a list of input items.

Close what you own. A RedisSession, MongoDBSession or DaprSession with a client the SDK created needs await session.close(), and the session is terminal afterwards — using it again raises RuntimeError. Pass your own client if you want to manage the lifetime yourself, which in a long-lived FastAPI process you usually do.

For readers working under Gulf or Egyptian data-residency rules, this section is where the decision gets made: a local session backed by Postgres or Redis in your own region keeps conversation text in your infrastructure, while conversation_id stores it with OpenAI. The SDK makes either work, but the choice is architectural, not a flag you flip later — the two cannot be mixed in one call.

MCP servers inside a running service

MCP — the Model Context Protocol — lets an agent use tools hosted by a separate server. The SDK supports three shapes, and only two are current.

from agents import Agent
from agents.mcp import MCPServerStdio, MCPServerStreamableHttp, create_static_tool_filter

async with MCPServerStreamableHttp(
    name="tickets",
    params={"url": "http://tickets.internal/mcp",
            "headers": {"Authorization": f"Bearer {token}"},
            "timeout": 10},
    cache_tools_list=True,
    max_retry_attempts=3,
    tool_filter=create_static_tool_filter(allowed_tool_names=["search", "get_ticket"]),
) as server:
    agent = Agent(name="Assistant", mcp_servers=[server])

MCPServerStdio launches a local process (params={"command": "npx", "args": [...]}) and suits a filesystem or git server running beside your app. MCPServerStreamableHttp is the network transport for new work. MCPServerSse is legacy — the MCP project deprecated the SSE transport — so do not start there. Hosted MCP is different again: HostedMCPTool(tool_config={"type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never"}) goes in tools, not in mcp_servers, and the call happens at OpenAI rather than in your process.

The performance fact that matters: every run calls list_tools() on every server. On a request path with three MCP servers that is three extra round trips before the first model call. cache_tools_list=True fixes it, and server.invalidate_tools_cache() is how you pick up a tool that changed. Local servers follow nextCursor pagination automatically for tools and prompts.

Server options worth setting deliberately: client_session_timeout_seconds, max_retry_attempts and retry_backoff_seconds_base for flaky networks; require_approval ("always", "never", True/False, or per-tool forms) for dangerous tools; tool_filter for least privilege; use_structured_content; failure_error_function; tool_meta_resolver; and tool_input_guardrails / tool_output_guardrails, which are the server-wide guardrails added in 0.22.1. On the agent side, mcp_config={"convert_schemas_to_strict": True, "failure_error_function": None, "include_server_in_tool_names": True} — that last key is the cure for name collisions between two servers that both expose search.

For several servers, MCPServerManager(servers) handles the lifecycle: active_servers, failed_servers, errors, drop_failed_servers=True so one dead server does not take down the agent, strict for the opposite policy, reconnect(failed_only=True), and connect_timeout_seconds / cleanup_timeout_seconds defaulting to ten seconds each.

Since 0.8.0 a local MCP tool failure returns error text to the model by default; set mcp_config={"failure_error_function": None} to fail fast instead. And note a version interaction: the SDK accepts mcp>=1.19.0,<3, so with MCP v2 installed your custom params["auth"] values and httpx_client_factory return types must be httpx2 types, or you pin mcp<2. params["ignore_initialized_notification_failure"]=True works only on v1.

Models, settings and providers

Model choice has a precedence order, and knowing it stops the "why is production on a different model" conversation: an explicit agent model beats RunConfig.model, which beats the OPENAI_DEFAULT_MODEL environment variable, which beats the SDK default.

The SDK default changed in 0.20.0 to gpt-5.6-luna, replacing gpt-5.4-mini. The implicit defaults reasoning.effort="none" and verbosity="low" did not change. The practical lesson is to set model explicitly on production agents, so that a minor-version bump cannot change which model your users talk to.

from openai.types.shared import Reasoning
from agents import Agent, ModelSettings

drafter = Agent(
    name="Drafter",
    model="gpt-5.6-luna",
    model_settings=ModelSettings(temperature=0.2, timeout=30.0, verbosity="low"),
)

analyst = Agent(
    name="Analyst",
    model="gpt-5.6-sol",
    model_settings=ModelSettings(
        reasoning=Reasoning(mode="pro", effort="max", context="all_turns"),
        max_tokens=4000,
    ),
)

ModelSettings carries the LLM parameters: temperature, top_p, frequency_penalty, presence_penalty, tool_choice, parallel_tool_calls, truncation, max_tokens, reasoning, verbosity, metadata, store, include_usage, response_include, top_logprobs, the extra_* escape hatches, retry, context_management, prompt_cache_options, preserve_raw_usage and timeout. Reasoning(mode=..., context=...) exists only on the Responses API — Chat Completions ignores those two with a warning. extra_args={"service_tier": "fast"} selects fast mode; "priority" is equivalent.

Retries are opt-in. The SDK does not retry model calls unless you set ModelSettings.retry; the single exception is conversation_locked, which is always retried.

from agents import ModelRetrySettings, ModelSettings, retry_policies

settings = ModelSettings(
    timeout=30.0,
    retry=ModelRetrySettings(
        max_retries=4,
        backoff={"initial_delay": 0.5, "max_delay": 5.0, "multiplier": 2.0, "jitter": True},
        policy=retry_policies.any(
            retry_policies.provider_suggested(),
            retry_policies.retry_after(),
            retry_policies.network_error(),
            retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]),
        ),
    ),
)

The helpers are never(), provider_suggested(), network_error(), http_status([...]), retry_after(), any(...) and all(...). Some requests are never retried regardless of policy: aborts, streams that already emitted output, and Programmatic Tool Calling side effects. Stateful requests using previous_response_id or conversation_id fail closed when replay safety is unknown, which is the correct default and worth knowing before you file a bug. ModelSettings(timeout=30.0) bounds each attempt and raises ModelTimeoutError; network_error() matches timeouts, so the two compose.

For non-OpenAI models there are four routes. set_default_openai_client(AsyncOpenAI(base_url=..., api_key=...)) sets one global client for an OpenAI-compatible endpoint. set_default_openai_api("chat_completions") switches the API, which you need when an endpoint does not implement Responses — the symptom is a 404. OpenAIChatCompletionsModel(model=..., openai_client=client) does it per agent. And the litellm/... or any-llm/... prefixes route through the default MultiProvider; both adapters are beta, and any-llm needs Python 3.11 or newer. Two non-OpenAI symptoms are worth memorising: BadRequestError about 'response_format.type' means the provider does not support JSON-schema structured output, so drop output_type or change provider; and the log line OPENAI_API_KEY is not set, skipping trace export means your models work but tracing has no key.

Streaming, and serving the SDK from a web app

The SDK is a library, not a server. There is no daemon and no control plane: it runs inside your process, whether that is FastAPI, Celery or a Temporal worker. State lives in your session store or at OpenAI. That means every operational property of your agent — concurrency, timeouts, restarts, graceful shutdown — is a property of the process you put it in.

Streaming is the common case for a user-facing service. Runner.run_streamed is not awaited; it returns a result whose stream_events() you iterate.

from openai.types.responses import ResponseTextDeltaEvent
from agents import Runner

async def token_stream(agent, user_text, session):
    result = Runner.run_streamed(agent, input=user_text, session=session)
    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            yield event.data.delta
        elif event.type == "run_item_stream_event" and event.name == "tool_called":
            yield "\n[looking that up…]\n"
        elif event.type == "agent_updated_stream_event":
            yield f"\n[handed off to {event.new_agent.name}]\n"

There are three event types — raw_response_event for token deltas and raw model events, run_item_stream_event for semantic items, and agent_updated_stream_event for handoffs. RunItemStreamEvent.name takes one of: message_output_created, handoff_requested, handoff_occured, tool_called, tool_search_called, tool_search_output_created, tool_output, reasoning_item_created, mcp_approval_requested, mcp_approval_response, mcp_list_tools. The misspelling in handoff_occured is deliberate, kept for backward compatibility. Do not "fix" it in your code; it will simply stop matching.

A workable FastAPI shape: connect MCP servers and create session clients in the lifespan handler; build agents once at import time, since they are cheap declarative objects; use await Runner.run(...) or Runner.run_streamed(...) per request, never run_sync; pass the authenticated user and tenant through context; and set workflow_name and group_id per request. For background workers, add flush_traces() after the work completes, because the batch processor exports asynchronously and a worker that exits immediately loses its traces.

Tracing and observability

Tracing is on by default. A trace is one end-to-end workflow, named "Agent workflow" unless you say otherwise; spans record the agent, generation, function, guardrail and handoff steps. The default span set is trace, task_span, turn_span, agent_span, generation_span, function_span, guardrail_span, handoff_span, transcription_span, speech_span and speech_group_span. Exports go to the OpenAI Traces dashboard, and the docs describe that tracing as free.

Three settings turn tracing from decoration into an operational tool. workflow_name should name the business process, not the code. group_id should be your thread or conversation ID, so every run in one conversation collapses into one view. trace_metadata should carry the tenant and the release version. And trace_include_sensitive_data=False keeps prompt and tool payloads out of the export, which is the setting to reach for when the conversation contains personal data.

from agents import Runner, RunConfig, trace, custom_span, flush_traces

with trace("nightly-reconciliation", group_id=batch_id):
    for invoice in invoices:
        with custom_span("invoice", data={"id": invoice.id}):
            await Runner.run(agent, invoice.text,
                             run_config=RunConfig(trace_metadata={"tenant": tenant, "rev": GIT_SHA},
                                                  trace_include_sensitive_data=False))
flush_traces()

trace_id must be formatted trace_<32 alphanumeric> if you supply your own. add_trace_processor(p) adds a destination; set_trace_processors([...]) replaces the default one, which is how you stop sending traces to OpenAI entirely. The docs list processors for Weights & Biases, Arize Phoenix, MLflow, Braintrust, Pydantic Logfire, AgentOps, LangSmith, Comet Opik, Langfuse, Langtrace, Galileo and others — so if your team already standardises on one of these, you add it rather than replace your agent code. If you need guaranteed redaction, put the redaction inside your own exporter: a separate processor that fails does not stop the other processors from exporting.

Two reasons you might see no traces at all: OPENAI_AGENTS_DISABLE_TRACING=1 or tracing_disabled, and a Zero Data Retention organisation, where OpenAI tracing is simply not available and a third-party processor is the only option. A different symptom, [non-fatal] Tracing client error 401, means traces are being sent with a non-OpenAI or invalid key; set_tracing_export_api_key(...) or RunConfig(tracing={"api_key": ...}) fixes it, and set_default_openai_key(key, use_for_tracing=False) keeps the two keys separate on purpose.

Plain Python logging is the other half. The loggers are openai.agents and openai.agents.tracing, and enable_verbose_stdout_logging() turns them up for a debugging session. By default, model and tool payloads are redacted in logs and errors (OPENAI_AGENTS_DONT_LOG_MODEL_DATA and OPENAI_AGENTS_DONT_LOG_TOOL_DATA both default to 1). Setting either to 0 is a development-only move.

Testing agents without calling a model

Non-deterministic tests are the reason agent code rots. Since 0.21 the SDK ships public testing utilities, and they are the difference between a suite you trust and a suite you skip.

import pytest
from agents import Agent, RunConfig, Runner
from agents.testing import ScriptedModel, assistant_message

@pytest.mark.asyncio
async def test_router_answers_from_script():
    model = ScriptedModel([[assistant_message("Paris is the capital of France.")]])
    agent = Agent(name="Geo", model=model)

    result = await Runner.run(agent, "Capital of France?",
                              run_config=RunConfig(tracing_disabled=True))

    assert result.final_output == "Paris is the capital of France."
    model.assert_complete()

ScriptedModel takes a list of turns, each a list of model outputs, so you can script a tool call followed by a final answer and assert on the whole path. assert_complete() fails if your agent made fewer calls than the script expected, which catches the case where a refactor accidentally short-circuits a turn. Note the import: agents.testing is not exported from top-level agents. There are matching agents.realtime.testing and agents.voice.testing modules.

Build the suite in three layers. Tool logic gets ordinary unit tests through tool.__wrapped__, which calls the plain function and skips validation, guardrails and tracing. Agent wiring gets ScriptedModel tests: that the right tool is called, that a handoff lands on the right agent, that a tripwire raises, that output_type parses. Model behaviour — did the answer stay on topic — belongs in a separate evaluation suite with a real model, run on a schedule rather than on every pull request; this is where RAGAS or promptfoo earn their place next to the SDK.

Always pass RunConfig(tracing_disabled=True) in tests. Otherwise every test run tries to export traces, which is slow, noisy and occasionally a 401 in CI. And test the guardrails through the runner, not by calling the guardrail function: the thing you want to assert is that the tripwire stopped the run, and that is runner behaviour.

Cost, latency and context size

Every lever below is one you now know; what follows is the order to pull them in.

Turns are the unit of cost. Each turn is a model call that resends the whole context. Cutting one turn from an eight-turn run saves more than any prompt edit. tool_use_behavior="stop_on_first_tool" removes a turn from every routing agent. Clear instructions about when not to call a tool remove more.

Context size is the second multiplier. A fifty-turn conversation resent in full on every turn is the usual cause of a bill that grows while traffic does not. SessionSettings(limit=N) is the blunt fix, session_input_callback the surgical one, truncation="auto" the server-side one, and compaction — either context_management=[{"type": "compaction", "compact_threshold": N}] or OpenAIResponsesCompactionSession — the one for threads that genuinely must stay long.

Model and effort come third. gpt-5.6-luna with the implicit reasoning.effort="none" for high volume; gpt-5.6-sol where frontier quality earns its price. Mixing them per agent inside one run is normal and is the single biggest cost lever in a multi-agent system: a cheap router, an expensive analyst, a cheap formatter.

Guardrail placement is a cost decision too. A cheap guardrail agent in blocking mode (run_in_parallel=False) costs one small model call and can save a large one. In parallel mode it costs the small call and the large one when it trips.

Tool-schema tokens are invisible but real. Twenty tools means twenty schemas in every request. ToolSearchTool() with defer_loading=True on the rarely-used tools cuts that, and it is Responses-only.

Then the mechanical levers: prompt caching via prompt_cache_options with explicit breakpoints — for GPT-5.6 use prompt_cache_options, not the legacy prompt_cache_retention; extra_args={"service_tier": "fast"} for latency or flex for cost; max_turns as a hard ceiling; max_function_tool_concurrency to protect downstream systems rather than tokens.

Measure before and after, from result.context_wrapper.usage. cached_tokens tells you whether caching took. reasoning_tokens tells you whether effort is really off. requests tells you your turn count. AdvancedSQLiteSession.store_run_usage(result) persists all of it for analytics, and ModelSettings(preserve_raw_usage=True) keeps the provider's raw numbers when you are reconciling against an invoice. LiteLLM and Any-LLM streaming may need include_usage=True before usage appears at all.

Debugging beyond the basics

At this level the failures are rarely "it crashed". They are "it took eleven model calls", "it stopped answering in production only", or "the tool ran twice".

Four errors at this level account for most tickets.

MaxTurnsExceeded: Max turns (10) exceeded is a loop. The usual causes are a tool whose output invites another call, instructions that never authorise finishing, or tool_choice="required" combined with reset_tool_choice=False — that agent field defaults to True precisely to break infinite tool loops, so if someone turned it off, that is your bug.

ModelRefusalError: Model refused to produce output: <refusal> has been an exception since 0.15.0. Code written against earlier versions expected an empty final_output or looped to MaxTurnsExceeded, so this is a classic upgrade surprise. Handle it with error_handlers={"model_refusal": lambda d: d.error.refusal}.

ModelBehaviorError for a Responses terminal status of failed or incomplete is new in 0.22.0 for non-streaming calls, matching what streaming already did. The usual cause is truncation against max_output_tokens. Raise the budget, consider truncation="auto", and add a retry policy.

Responses 400 Item 'rs_...' of type 'reasoning' was provided without its required following item. is a replayed reasoning item. RunConfig(reasoning_item_id_policy="omit") is the fix; the default is "preserve".

Error handlers are the graceful-degradation layer, available on all Runner methods:

from agents import RunErrorHandlerResult, Runner

result = await Runner.run(agent, user_text, max_turns=5, error_handlers={
    "max_turns": lambda d: RunErrorHandlerResult(
        final_output="I could not finish that. Could you narrow it down?",
        include_in_history=False),
    "model_refusal": lambda d: d.error.refusal,
})

include_in_history defaults to True. For a structured agent, a handler returning something that does not match output_type raises UserError: Invalid run error handler final_output for structured output., so return an instance of the type — or None to decline and let the original error propagate.

Putting it all together

A support agent you could put behind an endpoint, with every control from this level in its place.

import os
from dataclasses import dataclass
from pydantic import BaseModel
from openai.types.shared import Reasoning
from agents import (Agent, GuardrailFunctionOutput, ModelRetrySettings, ModelSettings,
                    RunConfig, RunContextWrapper, RunErrorHandlerResult, Runner,
                    handoff, retry_policies)
from agents.decorators import input_guardrail, tool
from agents.extensions import handoff_filters
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
from agents.extensions.memory import RedisSession
from agents.run import SessionSettings, ToolExecutionConfig

@dataclass
class Ctx:
    user_id: str
    tenant: str
    may_refund: bool

class Refund(BaseModel):
    order_id: str
    amount_cents: int

@tool(timeout=5.0, failure_error_function=None, needs_approval=True)
async def issue_refund(ctx: RunContextWrapper[Ctx], order_id: str, amount_cents: int) -> Refund:
    """Refund one order. Requires approval."""
    if not ctx.context.may_refund:
        raise PermissionError("tenant not permitted to refund")
    await billing.refund(ctx.context.tenant, order_id, amount_cents)
    return Refund(order_id=order_id, amount_cents=amount_cents)

@tool(timeout=5.0)
async def order_status(ctx: RunContextWrapper[Ctx], order_id: str) -> str:
    """Return the current status of one order."""
    return await orders.status(ctx.context.tenant, order_id)

@input_guardrail(run_in_parallel=False)
async def on_topic(ctx, agent, input) -> GuardrailFunctionOutput:
    verdict = await Runner.run(classifier, input, context=ctx.context,
                               run_config=RunConfig(tracing_disabled=True))
    return GuardrailFunctionOutput(output_info=verdict.final_output,
                                   tripwire_triggered=not verdict.final_output.on_topic)

SETTINGS = ModelSettings(
    timeout=30.0,
    retry=ModelRetrySettings(max_retries=3,
        backoff={"initial_delay": 0.5, "max_delay": 5.0, "multiplier": 2.0, "jitter": True},
        policy=retry_policies.any(retry_policies.retry_after(),
                                  retry_policies.network_error(),
                                  retry_policies.http_status([429, 500, 502, 503, 504]))),
)

billing_agent = Agent[Ctx](
    name="Billing",
    model="gpt-5.6-sol",
    model_settings=ModelSettings(reasoning=Reasoning(effort="medium"), timeout=45.0),
    handoff_description="Refunds, invoices and payment failures.",
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nResolve billing issues. Refunds need approval.",
    tools=[issue_refund],
)

triage = Agent[Ctx](
    name="Triage",
    model="gpt-5.6-luna",
    model_settings=SETTINGS,
    instructions=f"{RECOMMENDED_PROMPT_PREFIX}\nAnswer order questions yourself. "
                 "Transfer anything about money to Billing. Do not call a tool twice for one question.",
    tools=[order_status],
    handoffs=[handoff(billing_agent, input_filter=handoff_filters.remove_all_tools)],
    input_guardrails=[on_topic],
)

def run_config(tenant: str, thread_id: str) -> RunConfig:
    return RunConfig(
        workflow_name="support",
        group_id=thread_id,
        trace_metadata={"tenant": tenant, "rev": os.environ["GIT_SHA"]},
        trace_include_sensitive_data=False,
        session_settings=SessionSettings(limit=40),
        tool_execution=ToolExecutionConfig(max_function_tool_concurrency=4),
        tool_not_found_behavior="return_error_to_model",
        tool_name_collision_policy="error",
    )

async def handle(user_text: str, ctx: Ctx, thread_id: str, redis_url: str):
    session = RedisSession.from_url(thread_id, url=redis_url)
    result = await Runner.run(
        triage, user_text, context=ctx, session=session, max_turns=6,
        run_config=run_config(ctx.tenant, thread_id),
        error_handlers={"max_turns": lambda d: RunErrorHandlerResult(
            final_output="I could not finish that — could you narrow it down?",
            include_in_history=False)},
    )
    if result.interruptions:
        return {"status": "awaiting_approval", "state": result.to_state().to_json()}
    return {"status": "ok", "answer": result.final_output,
            "agent": result.last_agent.name,
            "turns": result.context_wrapper.usage.requests}

Every line maps back to a section:

Where you are now

You can trace a run turn by turn and say why each one happened, read everything a result carries, keep secrets out of the model's view while remembering they land in a serialised state, write tools whose schemas and failure behaviour you chose, pick between a handoff and an as-tool on the control-ownership question, place guardrails where they actually run, choose a session strategy that fits your data-residency constraints, connect MCP servers without paying a handshake per request, pin a model so an upgrade cannot move it, retry and time out deliberately, stream to a browser without losing the session write, trace with names an on-call engineer can search, and test the whole thing offline.

Senior takes every one of these further, with an ownership dimension. Human-in-the-loop as a system: RunState persisted, authenticated and consumed atomically. The trust model in full, including sandbox clients and what the Unix-local one does not isolate. Multi-tenancy, durable execution with Temporal or Dapr, upgrade playbooks across the 0.20–0.22 breaks, and where the SDK stops.

Sources

• OpenAI Agents SDK documentation
• Agents
• Running agents
• Results
• Streaming
• Tools
• Handoffs
• Orchestrating multiple agents
• Guardrails
• Context management
• Sessions
• Model context protocol (MCP)
• Models
• Configuring the SDK
• Tracing
• Usage
• Testing
• Visualization
• Human in the loop
• Release process and breaking changes
• openai/openai-agents-python on GitHub
• openai-agents on PyPI

At this level an interviewer is no longer checking whether you can define an agent. They are checking whether you have operated one: whether you know what the loop costs, where a guardrail actually runs, which state strategies conflict, and what you would look at first when a run that used to take two model calls now takes nine. The questions below are the ones that come up, with the reasoning a strong answer shows.

How to pitch your experience in ninety seconds

Lead with the shape of the system, not the library. Something like: "We run the OpenAI Agents SDK inside a FastAPI service — it is a library, not a server, so everything about concurrency and restarts is our process's problem. A cheap router agent on gpt-5.6-luna answers most requests and hands off to a specialist on gpt-5.6-sol for the expensive ones. History lives in Redis sessions in our own region. Tools have timeouts and schemas; the destructive one needs approval. We cap max_turns, we pin the model explicitly so an SDK upgrade cannot move it, and we log usage.requests per run because turns are the unit of cost."

That paragraph quietly demonstrates seven things: that you know the SDK is in-process, that you mix models by cost, that you considered data residency, that you understand turn-based cost, that you have met the default-model drift problem, that you use approvals, and that you measure. Interviewers notice the absence of marketing words.

Scenario: the agent used to take two model calls, now it takes nine

What you check first: result.context_wrapper.usage.requests and the trace, in that order. requests is the turn count, and if it is sitting just under max_turns you have a loop, not a slow model. The trace shows the sequence — which tool was called, how many times, whether a handoff happened you did not expect.

The three usual causes. First, a tool whose output invites another call: it returns a partial answer or a hint, and the model dutifully calls again. Second, instructions that never authorise finishing, so the model keeps looking for more work. Third, tool_choice="required" combined with reset_tool_choice=False — that agent field defaults to True precisely to break infinite tool loops, so someone having turned it off is a concrete bug, not a tuning question.

The subtle one worth mentioning. An output only counts as final when it matches the desired type and there are no tool calls. A model that writes a good answer and attaches a redundant tool call does not end the run; you pay another turn. That detail separates people who have read the loop from people who have read a blog post about it.

The fixes, in order. Tighten the instructions about when not to call a tool. Make tools return complete answers. For a pure routing agent, set tool_use_behavior="stop_on_first_tool" and remove a turn from every request. Keep max_turns low enough that a runaway run cannot outlive the HTTP timeout, and add error_handlers={"max_turns": ...} so the user gets a sentence instead of a 500.

Scenario: the guardrail "works" but the tool still ran

This is the question that most reliably separates levels, because the behaviour is by design.

Input guardrails run in parallel with the agent by default. The guardrail and the agent start together; when the tripwire fires, the run is cancelled — but the agent may already have spent tokens and already have executed a tool. If that tool wrote a row or sent an email, "the guardrail blocked it" is not true.

A strong answer states the trade-off rather than calling the default a bug: parallel mode buys latency, blocking mode buys safety. @input_guardrail(run_in_parallel=False) runs the guardrail first. You choose blocking mode when the agent's tools have side effects or when tokens are the thing you are protecting, and parallel mode for a latency-sensitive read-only assistant.

Then add the two placement facts. Input guardrails run only on the first agent of a run, so a specialist reached by handoff is not re-screened — if you need screening everywhere, put the guardrails on RunConfig or inside the tools. And output guardrails run only on the agent that produces the final output, always after it finishes, with no parallel option.

Finishing move: mention what tool guardrails do not cover. They apply to function tools and local MCP servers, not to handoffs, not to hosted tools like WebSearchTool or HostedMCPTool, and not to ShellTool or ApplyPatchTool. An agent whose only risky surface is a hosted tool is not protected by them at all.

Scenario: conversations are lost on deploy

The weak answer is "we need a database". The strong answer names the three strategies and the rule that makes them exclusive.

You can carry history manually with result.to_input_list(), in a session that loads before each run and saves after it, or in server-managed state via conversation_id or previous_response_id. conversation_id and previous_response_id cannot be used together, and neither can be combined with session — that raises UserError: Session persistence cannot be combined with conversation_id, previous_response_id, or auto_previous_response_id.

If the symptom is loss on deploy, the cause is almost certainly an in-memory SQLiteSession("thread_1") with no file path, or a file-backed SQLite database on an ephemeral container filesystem. SQLite sessions are for development. Production means RedisSession.from_url(...), SQLAlchemySession.from_url(...) over Postgres, MongoDB or Dapr, from agents.extensions.memory.

Two extras that make the answer sound operated rather than read. Sessions whose client the SDK created need await session.close(), and the session is terminal afterwards — reusing it raises RuntimeError. And in a streaming endpoint, the session write happens after the last token, so a client disconnect that makes you break out of stream_events() can lose the turn you thought you saved.

Trade-off: handoff or agent-as-tool?

The question is never "which is better". It is "who should own the conversation afterwards".

A handoff transfers control. The model sees transfer_to_<agent_name>, the specialist takes over, history moves with control, and result.last_agent becomes the specialist. That is right for customer-facing triage, where the billing specialist should keep talking to the user.

An agent as tool keeps control. agent.as_tool(...) makes the specialist a callable; the orchestrator gets the result and writes the final answer. That is right for translate, summarise, score and extract, and whenever one agent must own the voice of the response or combine several sub-results.

The detail that proves you have shipped both: a nested as-tool run does not inherit the parent's conversation unless you pass the same session. That isolation is usually what you want — a summariser does not need the whole thread, and not sending it is cheaper — but it means "the sub-agent did not know what the user said earlier" is expected behaviour.

Then the two constraints. Nested handoff history has been opt-in since 0.7.0, so do not assume the old default. And server-managed conversations do not support handoff input filters: if you are on conversation_id, your remove_all_tools filter is not running.

Trade-off: local sessions or OpenAI-managed conversations?

Local sessions keep conversation text in your own infrastructure, which is the answer that matters for teams under Gulf or Egyptian data-residency expectations: Redis or Postgres in your region, under your retention policy, with your encryption. The cost is that you now own a database, a retention job and a growth problem.

Server-managed state removes all of that. You create a conversation and pass conversation_id, and OpenAI holds the history. The costs are real: the conversation lives with the provider, you cannot combine it with a local session, handoff input filters do not apply, and — the one people hit — output guardrails cannot be combined with conversation_id, previous_response_id or auto_previous_response_id on the Responses path, because rejected output cannot be removed from server-managed history. That combination raises UserError.

So the decision rule is short: if you need output guardrails, handoff filters, or data residency, keep history local. Otherwise server-managed state is less code. Saying "it is architectural, not a flag we can flip later" is the sentence that lands, because the two genuinely cannot be mixed in one call.

Trade-off: where to spend reasoning budget

A good answer treats the model as a per-agent decision, not a per-system one. The SDK's default since 0.20.0 is gpt-5.6-luna with implicit reasoning.effort="none" and verbosity="low". Precedence runs explicit agent model → RunConfig.model → OPENAI_DEFAULT_MODEL → SDK default.

The pattern: a cheap router, an expensive specialist, a cheap formatter. One multi-agent run can use three models, and that mix is usually the biggest single cost lever available. For the specialist on Responses, Reasoning(mode="pro", effort="max", context="all_turns") is available — and mode and context exist only on Responses, so Chat Completions ignores them with a warning.

The operational half of the answer is more important than the tuning half: pin model explicitly in production. The SDK's default model changed in a minor release, and anyone relying on the default had their traffic move. Pin the package too — >=0.22,<0.23 — because the minor number is where breaking changes to public non-beta APIs live.

Scenario: intermittent 500s from the model provider

Start by stating the default, because most candidates get it wrong: the SDK does not retry model calls. Retries are opt-in through ModelSettings.retry, and the only always-retried case is conversation_locked.

from agents import ModelRetrySettings, ModelSettings, retry_policies

ModelSettings(
    timeout=30.0,
    retry=ModelRetrySettings(
        max_retries=4,
        backoff={"initial_delay": 0.5, "max_delay": 5.0, "multiplier": 2.0, "jitter": True},
        policy=retry_policies.any(retry_policies.retry_after(),
                                  retry_policies.network_error(),
                                  retry_policies.http_status([429, 500, 502, 503, 504])),
    ),
)

Then show you know what retrying cannot fix. Aborts, streams that already emitted output, and Programmatic Tool Calling side effects are never retried. Stateful requests using previous_response_id or conversation_id fail closed when replay safety is unknown — which is the right default, and knowing it stops you from filing it as a bug. ModelSettings(timeout=...) bounds each attempt and raises ModelTimeoutError; network_error() matches timeouts, so timeout plus retry compose into a sane per-request budget.

Tool-side resilience is the mirror image: @tool(timeout=5.0) with timeout_behavior="error_as_result" tells the model the tool timed out and lets it adapt, while "raise_exception" surfaces ToolTimeoutError. Mention that timeouts work on async tools only — a timeout on a sync tool does nothing.

Scenario: how would you test this?

The expected answer is three layers, and the giveaway that you have actually done it is that you name the import path.

Tool logic gets ordinary unit tests via tool.__wrapped__, which calls the original function and skips validation, guardrails and tracing. Agent wiring gets agents.testing.ScriptedModel — note it is not exported from top-level agents — with assistant_message(...) to script turns, and model.assert_complete() to catch a refactor that short-circuits a turn. Model behaviour, the did-it-answer-well question, belongs in a separate evaluation suite against a real model, run on a schedule rather than per pull request.

model = ScriptedModel([[assistant_message("Paris is the capital of France.")]])
agent = Agent(name="Geo", model=model)
result = await Runner.run(agent, "Capital of France?", run_config=RunConfig(tracing_disabled=True))

Two details that read as experience: always pass tracing_disabled=True in tests, otherwise CI tries to export traces and occasionally returns a 401; and test guardrails through the runner, because the assertion you care about is that the tripwire stopped the run, which is runner behaviour rather than function behaviour.

Scenario: latency spiked after we added MCP tools

The mechanism is the answer: every run calls list_tools() on every MCP server. Three servers means three round trips before the first model call. cache_tools_list=True removes them, and invalidate_tools_cache() is how you pick up a changed tool.

Second cause, and the one you find by reading the code rather than the trace: connecting per request. Using a server outside async with and without connect() raises UserError: Server not initialized..., so people wrap each request in async with — which adds a handshake to every user's latency. The fix is to connect in the FastAPI lifespan handler and keep an MCPServerManager on application state, with drop_failed_servers=True so one dead server degrades the agent instead of breaking it.

Third cause, token latency rather than network latency: every tool's schema is in every request. Twenty tools is twenty schemas. ToolSearchTool() with defer_loading=True on rarely-used tools cuts that, and it is Responses-only — as are tool_namespace() and Programmatic Tool Calling.

What a strong answer covers that a weak one misses

A weak answer describes the happy path and stops. A strong answer names the default, says whether it is the right one, and explains what it costs. Concretely, these are the markers interviewers listen for at mid level:

Two more habits make a visible difference. First, quantify: "mean 2.3 turns, 4,100 input tokens, 61% cached" is worth more than any adjective. Second, when you do not know something, say which source you would check — the release notes for a behaviour change, src/agents for a default. Admitting that the SDK's own docs and its source have disagreed, and that the source wins, is a mid-level answer in one sentence.

Sixty-second self-check

Answer out loud; each should take a few seconds.

1. What two conditions make an output final?
2. What is the default max_turns, and what does None do?
3. Which guardrail kind runs on only the first agent?
4. What does run_in_parallel=False buy, and cost?
5. Which three state strategies are mutually exclusive, and which pair raises UserError with output guardrails?
6. After a handoff, what is result.last_agent?
7. Does a nested as-tool run see the parent conversation?
8. What is strict_mode's default, and what breaks when a tool takes a free-form dict?
9. On which tools do @tool(timeout=...) limits work?
10. Does the SDK retry model calls by default?
11. Which field is the turn count on usage?
12. What removes the per-run MCP list_tools() round trip?
13. Where does result.final_output come back as None?
14. Which log environment variables redact model and tool payloads, and what are their defaults?
15. Why must you drain stream_events() to the end?

If any of those took longer than a breath, that section of the detailed guide is where to go back.

The errors at this level are not syntax errors. They are defaults you inherited, combinations the SDK rejects, and costs you did not measure. What follows is ordered by how much pain it removes per minute spent: the mistakes first, then the practices by leverage, then cards to rehearse, then recipes to copy.

The errors that cost the most time

MaxTurnsExceeded treated as a model problem. The symptom is Max turns (10) exceeded; the cause is almost always a loop. A tool returns a partial answer that invites another call, the instructions never authorise finishing, or someone set reset_tool_choice=False alongside tool_choice="required" — that agent field defaults to True specifically to break infinite tool loops. Raising max_turns hides the loop and multiplies the bill. Fix the loop, then set max_turns as a ceiling your HTTP timeout can tolerate, and add error_handlers={"max_turns": ...} so the user gets a sentence instead of a 500.

Assuming final_output is a string. It is a str only when the last agent has no output_type; otherwise it is an instance of that type, and it is None when the run paused on an approval. The day someone adds needs_approval=True to one tool, every handler that touches final_output without checking result.interruptions first starts throwing. Branch on result.interruptions before anything else.

Believing an input guardrail prevented the tool call. Input guardrails run in parallel with the agent by default. The tripwire cancels the run, but tokens may already be spent and a tool may already have executed. If the tool writes anything, use @input_guardrail(run_in_parallel=False).

Expecting guardrails to re-run after a handoff. Input guardrails run on the first agent only; output guardrails run only on the agent producing the final output. A specialist reached by handoff is not re-screened. Put the guardrails on RunConfig, or enforce inside the tools.

Fighting strict mode instead of modelling the input. strict_mode defaults to True. A tool taking dict[str, Any], or an output_type that is a union or nullable at the root, raises UserError: The root of a strict JSON schema must be a non-nullable object.... Reaching for strict_mode=False makes the model's job harder and your validation weaker. Wrap the value in a Pydantic model.

Letting a destructive tool swallow its own failures. With no failure_error_function, a raising tool returns "An error occurred while running the tool. Please try again." to the model, which will try again — on a refund, a delete, a ticket close. Pass failure_error_function=None explicitly on anything that mutates state, so the exception propagates and the run fails loudly.

Putting a timeout on a sync tool. @tool(timeout=...) works on async tools only. On a sync function it silently does nothing, and the blocking call occupies a worker thread for as long as it likes.

SQLite sessions in production. SQLiteSession("thread_1") is in-memory and dies with the process; the file-backed form dies with the container. Use RedisSession, SQLAlchemySession or MongoDBSession from agents.extensions.memory, and await session.close() on clients the SDK created — the session is terminal afterwards, and reusing it raises RuntimeError.

Mixing state strategies. Passing session= with conversation_id= or previous_response_id= raises UserError. So does an output guardrail combined with any of the three on the Responses path, because rejected output cannot be removed from server-managed history. Decide once, in your service layer, not per handler.

Running on the default model. It changed in 0.20.0 from gpt-5.4-mini to gpt-5.6-luna. Anyone relying on the default had their production traffic move on a version bump. Set model explicitly on every production agent and pin openai-agents>=0.22,<0.23.

Abandoning a stream early. Session writes, approval bookkeeping and compaction run after the last token. Break out of stream_events() on a client disconnect and you may lose the turn. The flip side: a stream that appears to hang after the final token is usually compaction working, not a bug.

Paying for list_tools() on every run. Every run calls it on every MCP server. Three servers, three round trips, every request. cache_tools_list=True, plus invalidate_tools_cache() when tools change.

Putting secrets in context and then persisting state. Local context is never sent to the model — but it is serialised into RunState. If you store to_state().to_json(), your database handle's credentials went with it.

The practices that pay off most, in order

1. Pin the model and the package. Two lines, and they remove a whole class of "nothing changed but the behaviour changed" incidents. Explicit model= on each agent beats RunConfig.model, which beats OPENAI_DEFAULT_MODEL, which beats the SDK default.

2. Log usage on every run. result.context_wrapper.usage gives you requests (your turn count), input_tokens, output_tokens, input_tokens_details.cached_tokens and output_tokens_details.reasoning_tokens. Without these you cannot tell a slow model from a loop, or a working cache from a hopeful one. Everything else in this list is easier once you have the numbers.

3. Name your traces. workflow_name for the business process, group_id for the thread, trace_metadata for tenant and release, trace_include_sensitive_data=False when the conversation carries personal data. An unnamed trace is a trace nobody searches.

4. Give every tool a schema, a timeout and a failure policy. Typed parameters and a real docstring are the contract the model reads. A timeout bounds the request. An explicit failure policy decides whether the model retries or the run fails.

5. Cap turns and tool concurrency. max_turns protects the user's latency and your bill. ToolExecutionConfig(max_function_tool_concurrency=N) protects your database, since local tools for one turn otherwise run unbounded. It is a different lever from ModelSettings(parallel_tool_calls=...), which decides whether the model emits parallel calls at all.

6. Bound history. SessionSettings(limit=N) first, session_input_callback when you need control over which items survive, truncation="auto" or server-side compaction for threads that must stay long.

7. Test with ScriptedModel. Offline, deterministic, seconds. Three layers: tool.__wrapped__ for logic, ScriptedModel for wiring, a scheduled evaluation suite for behaviour.

8. Connect MCP once, filter it down. Lifespan handler, MCPServerManager(drop_failed_servers=True), cache_tools_list=True, and a tool_filter that exposes only the tools this agent needs.

9. Set retries and timeouts deliberately. The SDK retries nothing by default except conversation_locked. A ModelSettings(timeout=30.0) plus a retry_policies.any(...) policy turns provider blips into latency instead of errors.

10. Mix models by cost inside one run. Cheap router, expensive specialist, cheap formatter. This is usually a larger saving than any prompt edit.

11. Choose your state home on purpose. Local sessions in your own region keep conversation text under your retention and encryption policy — the deciding factor for many Gulf and Egyptian employers. Server-managed conversations are less code but cost you output guardrails and handoff filters.

12. Keep redaction on. OPENAI_AGENTS_DONT_LOG_MODEL_DATA and OPENAI_AGENTS_DONT_LOG_TOOL_DATA both default to redacting. Turn them off for one debugging session, locally, and turn them back on.

Reading the messages the SDK actually prints

Half of operating this SDK is recognising a message and knowing which of the sections above it belongs to. These are the ones that show up in real logs, with what they mean rather than what they say.

AgentRunner.run_sync() cannot be called when an event loop is already running. — someone used Runner.run_sync inside a notebook, a FastAPI handler or another coroutine. await Runner.run(...) instead. It is the most common first error in a new service, and it is purely mechanical.

ModelBehaviorError: Invalid JSON input for tool <name> — the model sent malformed arguments. Note that with tool-data redaction on, the underlying validation error is not chained, so the stack trace tells you less than you expect. Set OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0 for one local run to see the payload, then simplify the schema. Keep strict_mode=True; a complicated schema is the cause, not the check.

ModelBehaviorError for a Responses terminal status of failed or incomplete — new in 0.22.0 for non-streaming calls, which brings them in line with streaming. The usual cause is truncation against the output-token budget. Raise max_tokens, consider truncation="auto", and add a retry policy.

ModelRefusalError: Model refused to produce output: <refusal> — a refusal has been an exception since 0.15.0. Code written before then expected an empty final_output or looped to MaxTurnsExceeded, so this is the classic symptom of an upgrade nobody re-read the notes for. Handle it with error_handlers={"model_refusal": lambda d: d.error.refusal}.

UserError: Server not initialized. Make sure you call connect() first. — an MCP server used outside async with and without connect(). The wrong fix is wrapping every request in async with; the right one is a lifespan handler.

Item 'rs_...' of type 'reasoning' was provided without its required following item. — a reasoning item ID was replayed without the item that should follow it, which happens when you rebuild input lists by hand. RunConfig(reasoning_item_id_policy="omit") fixes it; the default is "preserve".

OPENAI_API_KEY is not set, skipping trace export and [non-fatal] Tracing client error 401 — your models work and your traces do not. Both are normal when you run a non-OpenAI provider: the model client has one key and the trace exporter needs another. set_tracing_export_api_key(...), RunConfig(tracing={"api_key": ...}), or set_tracing_disabled(True) if you have a third-party processor instead. If you are a Zero Data Retention organisation, OpenAI tracing is simply unavailable and a third-party processor is the only route.

BadRequestError mentioning 'response_format.type' — a third-party provider that does not support JSON-schema structured output. Drop output_type or change provider. A bare 404 from a non-OpenAI endpoint usually means it does not implement the Responses API at all: set_default_openai_api("chat_completions") or an explicit OpenAIChatCompletionsModel.

A TypeError naming an unknown field — since 0.19 a misspelled key in a ModelSettings or RunConfig dict raises instead of being ignored. Annoying once, and a genuine improvement: a typo in a dict-shaped config used to silently disable the setting you thought you had set.

Finally, the exception attributes worth reaching for before you add print statements. Tripwire exceptions carry .guardrail_result and .run_data, or .guardrail and .output for tool guardrails. ToolTimeoutError carries .tool_name and .timeout_seconds. ModelRefusalError carries .refusal. Everything the SDK raises subclasses AgentsException, which is the right thing to catch at the edge of a handler when you want one fallback path for all of it.

Practice cards

Operational recipes

A per-run cost record. Put this after every Runner.run in a service and you can answer cost questions from your own logs:

u = result.context_wrapper.usage
metrics.observe("agent.turns", u.requests, tags={"agent": result.last_agent.name})
metrics.observe("agent.input_tokens", u.input_tokens)
metrics.observe("agent.cached_tokens", u.input_tokens_details.cached_tokens)
metrics.observe("agent.reasoning_tokens", u.output_tokens_details.reasoning_tokens)

A request-safe run wrapper. Turn cap, tracing names, tool policy and a graceful max-turns fallback in one place:

from agents import RunConfig, RunErrorHandlerResult, Runner
from agents.run import SessionSettings, ToolExecutionConfig

async def run_agent(agent, text, *, ctx, session, thread_id, tenant, rev):
    return await Runner.run(
        agent, text, context=ctx, session=session, max_turns=6,
        run_config=RunConfig(
            workflow_name="support",
            group_id=thread_id,
            trace_metadata={"tenant": tenant, "rev": rev},
            trace_include_sensitive_data=False,
            session_settings=SessionSettings(limit=40),
            tool_execution=ToolExecutionConfig(max_function_tool_concurrency=4),
            tool_not_found_behavior="return_error_to_model",
            tool_name_collision_policy="error",
        ),
        error_handlers={"max_turns": lambda d: RunErrorHandlerResult(
            final_output="I could not finish that — could you narrow it down?",
            include_in_history=False)},
    )

MCP in a FastAPI lifespan. Connect once, degrade rather than fail, cache the tool list:

from contextlib import asynccontextmanager
from agents.mcp import MCPServerManager, MCPServerStreamableHttp, create_static_tool_filter

@asynccontextmanager
async def lifespan(app):
    servers = [
        MCPServerStreamableHttp(
            name="tickets",
            params={"url": TICKETS_MCP_URL,
                    "headers": {"Authorization": f"Bearer {token}"},
                    "timeout": 10},
            cache_tools_list=True,
            max_retry_attempts=3,
            tool_filter=create_static_tool_filter(allowed_tool_names=["search", "get_ticket"]),
        ),
    ]
    manager = MCPServerManager(servers, drop_failed_servers=True)
    async with manager:
        app.state.mcp = manager
        yield

Put tokens in headers, never in the URL, and keep the filter tight — tool_filter is how an agent that only needs to read tickets stops seeing the tool that closes them.

Traces that survive a worker. BatchTraceProcessor exports in the background, so a Celery or RQ task that exits immediately loses its traces:

from agents import Runner, flush_traces, trace

def task(batch_id, items):
    with trace("nightly-reconciliation", group_id=batch_id):
        for item in items:
            asyncio.run(Runner.run(agent, item))
    flush_traces()

A debugging session you can turn off again. Three settings, in this order, locally only:

export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0      # see malformed tool arguments
export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0     # see the model payloads
python -c "from agents import enable_verbose_stdout_logging as v; v()"

The loggers are openai.agents and openai.agents.tracing. Unset both variables before committing anything.

A handoff that is authorised, not just routed. on_handoff is the only hook that runs between the model choosing a specialist and the specialist starting:

async def on_escalate(ctx, input_data) -> None:
    if not ctx.context.may_escalate:
        raise PermissionError("tenant not permitted to escalate")
    await audit.record(ctx.context.user_id, input_data.reason)

Raising there refuses the handoff. Remember that is_enabled controls what the model sees, not what it is allowed to do, and that tool arguments come from the model and are therefore untrusted input.

The checklist before you call it production

1. Model pinned, package pinnedExplicit model= on every agent; openai-agents>=0.22,<0.23 in the lockfile.
2. Turn and concurrency caps setmax_turns below your request timeout; max_function_tool_concurrency below your connection pool.
3. Every tool typed, timed and policiedPydantic or scalar parameters, a real docstring, an async timeout, and an explicit failure policy on anything destructive.
4. Approvals on anything irreversibleneeds_approval=True, and the handler branches on result.interruptions before final_output.
5. Guardrails placed where they runBlocking mode where tools have side effects; RunConfig guardrails or in-tool checks for agents reached by handoff.
6. One state strategy, chosen deliberatelyA production session backend, or server-managed state — never both, and never SQLite.
7. MCP connected once and filteredLifespan handler, cache_tools_list=True, drop_failed_servers=True, tokens in headers.
8. Retries and timeouts configuredModelSettings(timeout=...) plus a retry policy; nothing retries by default.
9. Traces named and usage loggedworkflow_name, group_id, trace_metadata, and flush_traces() in workers.
10. Offline tests greenScriptedModel coverage for answered, handed off, guardrail tripped and max turns, all with tracing_disabled=True.
11. Redaction left onBoth OPENAI_AGENTS_DONT_LOG_*_DATA variables at their defaults, and no secrets in context if you persist RunState.
12. Streams drainedNo break out of stream_events() that skips the session write.

Next in the catalogue, a trace destination you own is the usual follow-up — Langfuse plugs in as a trace processor without touching agent code — and for the behavioural testing this level deliberately leaves to a scheduled suite, RAGAS and promptfoo are where that work lives.

This is part three of three. Beginner showed you how to define an agent and run it. Mid showed you how the loop behaves, how sessions and handoffs work, and how to debug a run that goes wrong. This level assumes all of that and asks a different question: you are the person other teams file tickets against when their agent misbehaves, and the openai-agents dependency in twelve services is yours to version, secure, budget and upgrade. What do you have to own?

The honest starting point is that there is less to own than people expect, and the parts that exist are in unusual places. The SDK is a library, not a server. There is no control plane to run, no scheduler to tune, no cluster to size. What you own instead is a set of conventions, a small shared layer of code, a budget, and a trust model that the library deliberately leaves to you.

Where this picks up

Everything below is written against openai-agents 0.22.3 on Python 3.10 or newer. Version numbers matter more than usual here, because this project moves its minor number for breaking changes and has done so four times in two months.

The architecture you actually own

The first architectural fact to internalise, and the one that reframes every other decision, is that the SDK has no process of its own. It is imported into yours. If your API is FastAPI, the agent loop runs in a FastAPI worker. If your batch jobs are Celery tasks, it runs in a Celery worker. If you use Temporal, it runs inside an activity. There is no daemon, no sidecar, no admin port and no place to put an operator.

That has three consequences you will be asked about in design review.

First, capacity is your process's capacity. An agent run is mostly waiting on HTTP, so it is cheap in CPU and expensive in concurrency. A FastAPI worker handling agent runs will hold open connections for tens of seconds at a time. If you size the pool the way you size a CRUD service you will exhaust it. Size it from the product of expected concurrent conversations and the mean wall-clock duration of a run, then add headroom for the long tail that approvals introduce.

Second, durability is not included. The loop is in-memory. If the process dies mid-run, the run is gone, along with any local tool side effects it had already committed. Anything that must survive a deploy has to be written down, either by you serializing RunState into your own database, or by delegating to a durable execution engine. The SDK ships integrations for Temporal, Dapr, Restate and DBOS for exactly this reason.

Third, state lives in two places and you choose which. Either it lives in a session store you operate — SQLite, Redis, Postgres through SQLAlchemy, MongoDB, a Dapr state store — or it lives at OpenAI, through the Conversations API or by chaining previous_response_id. These two strategies are mutually exclusive per call, and the SDK enforces that: passing both session= and conversation_id raises UserError: Session persistence cannot be combined with conversation_id, previous_response_id, or auto_previous_response_id.

Failure modes of the agent loop

The loop has a small number of ways to end badly, and every one of them has a specific exception. Learning them as a set is worth more than any amount of generic retry logic, because the correct response differs sharply between them.

The loop never terminates on its own. MaxTurnsExceeded: Max turns (10) exceeded is the backstop. A turn is one model call, not one user message, so ten turns is ten round trips. The usual causes are a tool whose output invites another identical call, or tool_choice="required" combined with reset_tool_choice=False, which tells the model it must call a tool on every single turn forever. reset_tool_choice defaults to True precisely to prevent that, and turning it off is a decision to be defended in review.

The model refuses. Since 0.15.0 a refusal raises ModelRefusalError: Model refused to produce output: <refusal> with the text on .refusal. Before that version it surfaced as an empty final_output or as a loop that ran to MaxTurnsExceeded, so any code you inherit that checks if not result.final_output is testing for a condition that no longer occurs.

The response is truncated or fails server-side. Since 0.22.0 a non-streaming Responses call whose terminal status is failed or incomplete raises ModelBehaviorError, which brings it in line with what streaming already did. The common trigger is hitting max_output_tokens. This is a genuine behaviour change: code that previously received a short answer now receives an exception.

A model call hangs. The SDK does not time out model calls unless you say so. ModelSettings(timeout=30.0) bounds each attempt and raises ModelTimeoutError: Model call timed out after 30 seconds.

A tool hangs. @tool(timeout=...) works on async tools only. The default timeout_behavior="error_as_result" hands the timeout text back to the model, which may then try something else; "raise_exception" raises ToolTimeoutError: Tool 'slow_lookup' timed out after 2 seconds. with .tool_name and .timeout_seconds attached. Which behaviour you want is a product decision, not a default to accept silently.

The platform response to all of this is not a try/except ladder at every call site. It is error_handlers, which every Runner method accepts and which lets you convert a class of failure into a defined output.

from agents import RunErrorHandlerInput, RunErrorHandlerResult, Runner

DEFAULT_ERROR_HANDLERS = {
    "max_turns": lambda d: RunErrorHandlerResult(
        final_output="I could not finish that within the step budget. Please narrow the request.",
        include_in_history=False,
    ),
    "model_refusal": lambda d: d.error.refusal,
}

async def run(agent, user_input, **kwargs):
    kwargs.setdefault("error_handlers", DEFAULT_ERROR_HANDLERS)
    return await Runner.run(agent, user_input, **kwargs)

Retries deserve their own paragraph because the default surprises people: the SDK does not retry model calls at all unless ModelSettings.retry is set. The single exception is conversation_locked, which is always retried. Everything else — a 429, a dropped connection, a 503 — fails the run.

from agents import ModelRetrySettings, ModelSettings, retry_policies

PLATFORM_DEFAULTS = ModelSettings(
    timeout=45.0,
    retry=ModelRetrySettings(
        max_retries=4,
        backoff={"initial_delay": 0.5, "max_delay": 5.0, "multiplier": 2.0, "jitter": True},
        policy=retry_policies.any(
            retry_policies.provider_suggested(),
            retry_policies.retry_after(),
            retry_policies.network_error(),
            retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]),
        ),
    ),
)

Jitter is not optional at platform scale. Without it, a provider incident synchronises every one of your workers onto the same retry schedule and you hand the recovering API a thundering herd. Note also what is never retried regardless of policy: aborted requests, streams that already emitted output, and the side effects of Programmatic Tool Calling. Stateful requests using previous_response_id or conversation_id fail closed when replay safety cannot be established, and RetryDecision(approve_unsafe_replay=True) can override that but only for non-streaming requests. That is a correctness guard, not a bug.

Which component breaks first

When you scale an agent platform, the parts fail in a fairly predictable order. Knowing the order lets you instrument ahead of the pain rather than behind it.

First: turn count, as a cost line. Each turn is a model call. max_turns defaults to 10, so a badly specified agent can quietly cost ten times what a well specified one does for the same user question. This is the first thing to graph and the first thing to alert on. max_turns=None disables the limit entirely, which is appropriate in a controlled batch job and close to negligent in a user-facing path.

Second: context length. History grows, tool results are verbose, and the input token count per turn climbs until latency becomes visible and cost becomes indefensible. You have five levers and they compose: RunConfig(session_settings=SessionSettings(limit=50)) to cap retrieval, a session_input_callback to merge history selectively, call_model_input_filter to rewrite the model input immediately before the call, ModelSettings(truncation="auto"), and server-side context_management=[{"type": "compaction", "compact_threshold": N}]. OpenAIResponsesCompactionSession wraps another session and compacts on a trigger you supply.

Third: MCP tool listing. Every run calls list_tools() on every attached server. With four servers and a thousand runs an hour that is four thousand round trips doing nothing useful. cache_tools_list=True fixes it, with invalidate_tools_cache() for when a server genuinely changes. MCPServerManager lifecycle timeouts default to ten seconds, which is a long time to spend starting a run that is going to fail.

Fourth: tool concurrency. Local tools in a turn run concurrently and unbounded by default. If a model emits eight parallel calls to a tool that opens a database connection, you have eight connections from one turn. RunConfig(tool_execution=ToolExecutionConfig(max_function_tool_concurrency=4)) bounds it. This is distinct from ModelSettings(parallel_tool_calls=...), which controls whether the model emits parallel calls at all; one is a brake on your side, the other a request to the model.

Fifth: the session store. SQLiteSession is for development. It has no integrity protection, and concurrent access was enough of a problem that 0.22.3 shipped a fix for concurrent SQLite startup. In production use RedisSession, SQLAlchemySession against Postgres, MongoDBSession or a Dapr state store, and close clients you own with await session.close(). A closed session is terminal; using it again raises RuntimeError.

Guardrails have a scaling property that catches teams out. Input guardrails run in parallel with the agent by default. That is the right latency trade-off for a moderation check, but it means a tripped guardrail may have already spent tokens and, worse, already run tools. If the guardrail exists to stop something expensive or irreversible, you must use blocking mode:

from agents.decorators import input_guardrail

@input_guardrail(run_in_parallel=False)   # runs first, blocks the agent until it returns
async def no_bulk_refunds(ctx, agent, input): ...

Output guardrails have no such option. They always run after the agent finishes, which is why they cannot coexist with server-managed conversation state at all.

The trust model

This is the section to read twice, because the SDK is explicit that several things people assume are security boundaries are not.

Tool arguments are model output, and model output is untrusted input. The model decides what to pass to delete_account(user_id). The user may have talked it into that. The correct place for authorisation is inside the tool body, or in a tool input guardrail, or behind an approval — never in the prompt.

is_enabled controls visibility, not permission. A tool with is_enabled=lambda ctx, agent: ctx.context.is_admin is hidden from non-admins, which is good for token budget and prompt hygiene. It is not an access control, because anything that can reach the tool object can call it. Same for MCP tool_filter: it shapes what the model sees. Enforce the real check inside the tool.

Local context is never sent to the LLM — but it is serialized. Runner.run(..., context=obj) gives tools and hooks a RunContextWrapper[T], and the model never sees it. That makes it the right home for a tenant ID, a user ID and a request ID. It is the wrong home for a database password, because result.to_state() serializes context into the RunState snapshot you may then persist.

RunState deserialization performs no authentication. This is the sharpest edge in the whole SDK. await RunState.from_json(agent, data) will faithfully reconstruct whatever snapshot you hand it, including the pending tool calls it will execute on resume. If a snapshot travels through a client, a user can edit the arguments of an approved tool call. The rules that follow are not optional:

Approval callables fail closed, which is the one piece of good news. If a needs_approval callable receives arguments that are malformed or not a JSON object, the call requires manual approval rather than sailing through. Build on that: default to approval and allow-list the exceptions.

The approval surface is wider than function tools. needs_approval exists on function tools, on as_tool, on ShellTool and on ApplyPatchTool. Local MCP servers use require_approval instead, accepting "always", "never", a bool, or per-tool forms. Hosted MCP uses tool_config={"require_approval": "always"} together with an on_approval_request callback. ShellTool and ApplyPatchTool default to needs_approval=False, which is a default worth overriding in your platform wrapper on day one. An approval is a human gate, not a sandbox; your executor still has to enforce isolation.

Sandboxes are not uniformly sandboxes. The Unix-local client provides no OS confinement on Linux. On macOS it uses sandbox-exec for filesystem restrictions with no network isolation. For anything driven by untrusted input, that means Docker — optionally with networking disabled — or a hosted provider such as E2B, Modal, Daytona, Runloop, Vercel, Cloudflare or Blaxel. Since 0.17.0, LocalFile.src and LocalDir.src must sit inside the process base directory unless you grant access explicitly with Manifest(extra_path_grants=(SandboxPathGrant(path=..., read_only=True),)), and those grants must come from trusted configuration, never from model output.

History filters do not redact. handoff_filters.remove_all_tools removes tool calls from the handed-off history; it does not redact anything from what remains. Nested handoff history, which has been opt-in and off by default since 0.7.0, does not redact either. If a specialist agent must not see a card number that appeared earlier in the conversation, you write a custom input_filter over HandoffInputData that removes it.

A session ID is not authentication. It is a lookup key. Anyone who can guess or obtain one can read the conversation unless you check authorisation yourself. EncryptedSession adds encryption at rest and a TTL, but it does not verify that history is complete or in order.

Secrets and the supply chain

Key handling has two paths and you should use the explicit one. The OPENAI_API_KEY environment variable is read lazily, when the first client is created, which is convenient and also means a missing key fails at first use rather than at import. In a platform wrapper, prefer loading from your secret manager at startup and calling set_default_openai_key(key) or set_default_openai_client(client). If you manage secrets with Vault, that is the integration point — see the Vault guide for the retrieval side.

The tracing key is separable, and separating it is good hygiene. set_tracing_export_api_key(...) or RunConfig(tracing={"api_key": ...}) sets the key traces are exported with, and passing use_for_tracing=False when you set the model client stops the model key being reused for export. That lets a tracing key be scoped differently, rotated on a different schedule, and revoked without taking inference down.

Redaction is on by default and should stay on. OPENAI_AGENTS_DONT_LOG_MODEL_DATA and OPENAI_AGENTS_DONT_LOG_TOOL_DATA both default to 1, meaning payloads are kept out of logs and exceptions. Setting either to 0 is a development-only action. Separately, trace_include_sensitive_data defaults to True, so traces do carry inputs and outputs unless you set RunConfig(trace_include_sensitive_data=False) or the OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0 environment variable. Those two controls are independent: redacted logs with unredacted traces is a common and unintended combination.

RunState includes the tracing API key only if you pass include_tracing_api_key=True. Do not, unless you have a specific reason and a plan for where snapshots live.

import os
from agents import (
    set_default_openai_client,
    set_tracing_export_api_key,
    add_trace_processor,
)
from openai import AsyncOpenAI

def bootstrap(secrets) -> None:
    """Call once at process start, before any agent is constructed."""
    client = AsyncOpenAI(api_key=secrets["openai_inference_key"])
    set_default_openai_client(client, use_for_tracing=False)
    set_tracing_export_api_key(secrets["openai_tracing_key"])
    add_trace_processor(our_redacting_processor())
    assert os.environ.get("OPENAI_AGENTS_DONT_LOG_TOOL_DATA", "1") == "1"

The supply chain has three strands.

The package itself. Pin it. The project's versioning policy is explicit: the minor number goes up for breaking changes to any non-beta public API, and the patch number covers bug fixes, new features, private-interface changes and changes to beta features. The docs recommend pinning to 0.Y.x, so openai-agents~=0.22.3 or >=0.22,<0.23. Note the implication that a patch release can change a beta feature; if you depend on sandbox agents or nest_handoff_history, patch bumps need reading too.

The transitive dependency surface. At 0.22.3 the core dependencies are openai>=3.0.0,<4, pydantic>=2.12.2,<3, griffelib>=2,<3, typing-extensions, requests, websockets>=15,<17, mcp>=1.19.0,<3 and httpx2>=2.12.0. Legacy httpx stopped being a direct dependency in 0.21.0. If your service passes http_client= to AsyncOpenAI, every client, transport, auth flow, event hook, mock transport and exception handler in that path has to move from httpx to httpx2; the docs point at openai.DefaultAsyncHttpx2Client. This is the single most disruptive change in recent memory and it arrived in a minor bump.

MCP servers. An MCP server is third-party code with tools your model can call. Connect only to servers you trust, scope tokens to the minimum, put them in headers rather than in the URL where they end up in logs, and require approval for anything with side effects. Note also that MCPServerSse is legacy, because the MCP project deprecated the SSE transport; new work uses MCPServerStreamableHttp or MCPServerStdio. The MCP guide covers the protocol side.

from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    name="billing",
    params={
        "url": "https://mcp.internal/billing/mcp",
        "headers": {"Authorization": f"Bearer {scoped_token}"},
        "timeout": 10,
    },
    cache_tools_list=True,
    max_retry_attempts=3,
    require_approval="always",
) as server:
    agent = Agent(name="Billing", mcp_servers=[server])

Multi-tenancy

Multi-tenancy in this SDK is built out of three pieces you already know, used deliberately: session IDs, typed context, and trace metadata. There is no tenant primitive, so the discipline has to come from your wrapper.

Session identity. One session ID per user or per thread, and authorisation performed by you before the session is ever constructed. The pattern that works is a factory that takes an authenticated principal and returns a session whose ID is derived from it, so no call site can accidentally build a session ID from a path parameter. Custom sessions can accept a wrapper keyword to receive the RunContextWrapper, which is the hook for routing a session to per-tenant storage.

Typed context. Put the tenant ID, the user ID and the request ID into a frozen dataclass and pass it as context. Every agent and tool in a run must share the same context type, which sounds restrictive and is actually the feature: it means a tool cannot be reused across two agents with incompatible tenancy assumptions without the type system noticing.

from dataclasses import dataclass

@dataclass(frozen=True)
class TenantContext:
    tenant_id: str
    user_id: str
    request_id: str
    entitlements: frozenset[str]

Then gate tool exposure on entitlements and enforce the real check inside the tool body:

from agents import RunContextWrapper
from agents.decorators import tool

def requires(entitlement: str):
    return lambda ctx, agent: entitlement in ctx.context.entitlements

@tool(is_enabled=requires("billing.write"), needs_approval=True)
async def issue_credit(ctx: RunContextWrapper[TenantContext], amount_cents: int) -> str:
    """Issue an account credit in the smallest currency unit."""
    if "billing.write" not in ctx.context.entitlements:   # the real check
        raise PermissionError("not entitled")
    return await billing.credit(ctx.context.tenant_id, amount_cents)

The duplication between is_enabled and the body is intentional and should be a review rule. The first saves tokens and keeps the prompt honest; the second is the control.

Sandbox workspaces. Use separate sandbox sessions per tenant. Unix-local sessions get separate temporary workspaces by default, but separate directories are not OS isolation, and this is precisely the case where Docker or a hosted provider becomes mandatory rather than advisable.

Trace partitioning. group_id — a chat thread ID is the canonical choice — and trace_metadata give you per-tenant filtering in the dashboard and in third-party processors. Do not put PII in either, because IDs leak into more places than payloads do.

For teams in the Gulf and Egypt there is a data-residency dimension that is easy to miss. Tracing exports conversation content to OpenAI by default. If a tenant's contract or a regulator requires that content stay in a particular jurisdiction, you need RunConfig(tracing_disabled=True) or trace_include_sensitive_data=False for that tenant, plus a session backend in the right region, plus a decision about whether server-managed conversations are acceptable at all. Note that organisations on Zero Data Retention get no OpenAI tracing whatsoever — the capability is simply unavailable — so a self-hosted processor is the only observability route. Langfuse is the common choice when the traces have to stay on your infrastructure.

Cost control as a platform function

Agent cost is not a model-price question, it is a turn-count question. The same model answering the same question costs four times as much if the agent takes four turns instead of one. Platform cost control therefore starts with measurement, and the SDK gives you more than most teams use.

result.context_wrapper.usage carries requests, input_tokens, output_tokens, total_tokens and request_usage_entries, plus input_tokens_details.cached_tokens and cache_write_tokens, and output_tokens_details.reasoning_tokens. That last field is the one to watch: reasoning tokens are output tokens you never see in the response text, and a reasoning effort set too high is the most common invisible cost. ModelSettings(preserve_raw_usage=True) keeps the provider's raw usage alongside the normalised view, which matters when you are reconciling against an invoice. LiteLLM and Any-LLM streaming may need include_usage=True to report at all. AdvancedSQLiteSession.store_run_usage(result) persists usage for analytics if you want the numbers in the same place as the conversations.

The levers, roughly in order of how much they return for the effort:

1. Model choice. The default gpt-5.6-luna with the implicit reasoning.effort="none" and verbosity="low" is the high-volume option. gpt-5.6-sol is the frontier option. Routing by request class rather than using one model everywhere is usually the single biggest saving available.
2. Turn and concurrency budgets. A max_turns appropriate to each agent, and max_function_tool_concurrency so a fan-out cannot multiply tool-side cost.
3. Prompt caching. prompt_cache_options with explicit breakpoints. Note that prompt_cache_retention, accepting "in_memory" or "24h", is the legacy control for earlier model families; for GPT-5.6 use prompt_cache_options.
4. Context discipline. Compaction and session limits reduce input tokens on every single turn, which compounds.
5. Cheap guardrails in blocking mode. A small model screening input before an expensive agent runs saves the whole run, but only if it blocks. In the default parallel mode the expensive agent has already started.
6. Service tier. ModelSettings(extra_args={"service_tier": "fast"}), with "priority" equivalent, and "flex" where latency is not critical.
7. Tool-schema cost. ToolSearchTool() with defer_loading=True on individual tools cuts the tokens spent sending dozens of schemas on every turn. Both are Responses-only.

Tracing to the OpenAI dashboard is free, so observability is not on the cost-cutting list.

Upgrades and migrations

Four minor versions landed between 2026-08-11 and 2026-08-19. If you are running this as a platform, upgrades are a recurring scheduled activity, not an event.

The checklist for landing on 0.22.x from anything older has six items, and they are in dependency order:

1. openai v3 and httpx2. Only bites if you pass a custom http_client. When it bites, it bites hard.
2. MCP v2 types. With MCP Python SDK v2 installed, custom params["auth"] values and httpx_client_factory return types must be httpx2 types. Pin mcp<2 if you are not ready. Note that params["ignore_initialized_notification_failure"]=True works on v1 only.
3. Default-model drift. Set model explicitly on every production agent. Precedence runs from an explicit agent model, then RunConfig.model, then the OPENAI_DEFAULT_MODEL environment variable, then the SDK default. Relying on the last of those means a minor upgrade silently changes your model, your latency and your bill.
4. ModelRefusalError handling. Add the "model_refusal" error handler before you upgrade past 0.15.0, not after.
5. OpenAIProvider argument conflicts. Move organization, project, api_key, base_url and websocket_base_url onto the AsyncOpenAI client.
6. Non-streaming failed/incomplete now raises. Find the code paths that quietly accepted a truncated answer.

Two subtler 0.22.0 changes deserve explicit mention because they do not announce themselves. Agent.clone() is a shallow copy: list attributes you do not override remain the same list object, so a clone that appends a tool mutates the original. Always pass a fresh list for anything the clone should own. And each RunResult.to_state() checkpoint now owns an independent usage snapshot, which changes what accounting code reading usage off a resumed state will report.

import pytest
from agents import Agent, RunConfig, Runner
from agents.testing import ScriptedModel, assistant_message

@pytest.mark.asyncio
async def test_single_turn_contract():
    model = ScriptedModel([[assistant_message("Paris is the capital of France.")]])
    agent = Agent(name="Geo", model=model)
    result = await Runner.run(
        agent, "Capital of France?", run_config=RunConfig(tracing_disabled=True)
    )
    assert result.final_output == "Paris is the capital of France."
    model.assert_complete()

Pin the SDK, run this suite against the next minor in a scheduled branch, and read the breaking-change changelog in the release docs before the bump rather than during the incident.

One migration-specific hazard: when approvals can wait days, a serialized RunState outlives deploys. Store an SDK version marker and an agent-definition version marker next to every snapshot, and decide explicitly what happens when a snapshot is older than the code — resume, refuse, or re-run from the original input. Refusing with a clear message is almost always the right answer.

Governance and incident playbooks

Governance here means a small number of rules enforced in code rather than in a wiki page, plus named playbooks for the failures you will actually see.

The rules worth enforcing in the wrapper, because no review process catches them reliably:

• Every agent sets model explicitly and max_turns explicitly.
• Every run has a workflow_name and a group_id.
• Every tool with side effects either requires approval or documents in its docstring why it does not.
• ShellTool and ApplyPatchTool are not available without an explicit platform exemption.
• Mandatory input guardrails are injected by run(), not left to call sites. RunConfig also accepts input_guardrails and output_guardrails at run level, which is where platform-wide policy belongs.
• Trace redaction settings are set once at bootstrap and asserted.

One note on redaction and processors. add_trace_processor adds a destination and set_trace_processors replaces the default. For guaranteed redaction, put the redaction inside your own exporter, because a separate redacting processor that fails does not stop the other processors from exporting. That is a design detail with compliance consequences.

Now the playbooks. Each one is a symptom, the first thing to check, and the fix.

Cost spike overnight. Check turns per run first, then reasoning tokens, then whether anyone deployed an agent without an explicit model into a window where the SDK default changed. The fix for the first is usually instructions, not budget; a tool whose output invites re-calling is the classic cause. Cap max_turns as the immediate mitigation and fix the instructions as the real one.

Latency regression with no deploy. Check input tokens per turn. Context has grown. Apply SessionSettings(limit=N) or enable compaction. Then check whether an MCP server got slower, since list_tools() runs per run and its latency is on the critical path of every single run.

Traces missing for background jobs. BatchTraceProcessor exports in the background, so a worker that exits promptly loses the batch. Call flush_traces() after the trace() block closes in Celery tasks, RQ jobs and FastAPI background tasks. If traces are missing everywhere rather than just in workers, check for a ZDR organisation, OPENAI_AGENTS_DISABLE_TRACING=1, or tracing_disabled. The log line OPENAI_API_KEY is not set, skipping trace export and the non-fatal Tracing client error 401 both point at the tracing key rather than the model key — common when the models come from a non-OpenAI provider.

A tool executed that should not have. Reconstruct from traces which agent called it with what arguments. Then ask the structural question: was the control an is_enabled callback rather than a check inside the tool? That is the bug in most of these incidents. Add the in-tool check and a tool input guardrail, and consider needs_approval.

An approval resumed twice. You are missing atomic consumption of the snapshot. Mark snapshots single-use in the same transaction that reads them.

A third-party provider rejects structured output. The signature is BadRequestError: Error code: 400 complaining that 'response_format.type' is not one of ['text','json_object']. The provider does not support JSON-schema structured outputs. Use one that does, or drop output_type. A 404 from a non-OpenAI endpoint usually means it does not implement the Responses API at all: set_default_openai_api("chat_completions") or an explicit OpenAIChatCompletionsModel. LiteLLM is the usual broker when you need several providers behind one interface.

Where the Agents SDK stops

A platform owner's most valuable skill is saying "not this tool" early. The documentation itself gives the first boundary: call the Responses API directly if you want to own the loop, tool dispatch and state yourself; use the SDK if you want a runtime that handles turns, tools, guardrails, handoffs, sessions or sandboxes. If your "agent" is one model call with a schema, you do not need a runtime, and adding one costs you a dependency with a fast-moving minor version.

Durable, long-running workflows. Runs measured in hours or days, with human approvals and process restarts in the middle, are not what an in-process loop is for. You have two routes: serialize RunState into your own database and rebuild the orchestration yourself, or use the Temporal, Dapr, Restate or DBOS integrations. For anything with more than one human gate, take the second route. If the workflow is better described as a DAG of mostly deterministic steps with one model call in the middle, it belongs in Prefect or Airflow with the agent as a task.

Explicit, inspectable graph control. The SDK's orchestration is either the model choosing — handoffs and agents-as-tools — or your own Python chaining, asyncio.gather and evaluator loops. If what you need is a graph you can draw, version and reason about statically, with conditional edges and checkpointing as first-class concepts, LangGraph is built for that shape and this SDK is not.

Provider portability as a requirement. The SDK speaks the Responses API natively and reaches other providers through base_url, OpenAIChatCompletionsModel, and the beta LiteLLM and Any-LLM adapters. A long list of Responses-only features — ToolSearchTool, tool_namespace(), defer_loading=True, ProgrammaticToolCallingTool, allowed_callers, tool_choice="programmatic_tool_calling" — are rejected on Chat Completions. Hosted tools such as WebSearchTool, FileSearchTool, CodeInterpreterTool, ImageGenerationTool and HostedMCPTool work with OpenAI Responses models only. If genuine multi-provider parity is a contractual requirement, build the abstraction a level lower.

Browser-side voice. RealtimeAgent and RealtimeRunner are server-side WebSocket only in Python, with SIP and telephony support. Python has no browser WebRTC transport. A browser voice client needs the JavaScript SDK or your own WebRTC layer.

Isolation of untrusted code. Covered above and worth repeating as a stopping point rather than a caveat: if untrusted input drives execution, the Unix-local sandbox client is not a boundary. Use Docker or a hosted provider, or do not run the code.

One mismatch to name explicitly, because it burns a day of debugging: OpenAI ships a separate JavaScript/TypeScript SDK. Their APIs are not the same. The Python result object has no output property; it has final_output. Blog posts and model-generated snippets mix the two freely.

Running it as a platform for other teams

The deliverable is not documentation, it is the wrapper package plus a paved road. Five things in it earn their maintenance cost.

A bootstrap() that is called once. Clients, keys, tracing processors, redaction assertions. Nothing else in your organisation calls set_default_openai_client or set_tracing_export_api_key.

A run() that applies policy. Platform guardrails, default ModelSettings including timeout and retry, default error_handlers, workflow_name and group_id derived from the request, session construction from an authenticated principal, and usage metrics emitted on the way out. Teams pass an agent and an input; they do not pass a RunConfig. Anywhere a RunConfig is accepted a plain dict works too, and since 0.19.0 an unknown key in such a dict raises TypeError rather than being ignored — which makes dict-based config safe enough for a declarative layer if you want one.

An agent registry. Agents declared in one place with an owner, an explicit model, an explicit max_turns, a cost budget and a review date. This is what lets you answer "which agents can issue refunds" in seconds rather than with a grep.

A tool library with tiers. Read-only tools available to everyone, side-effecting tools requiring approval and an entitlement, and a small privileged tier requiring a platform exemption. Tool input and output guardrails on anything touching money or personal data. Remember what tool guardrails do not cover: they apply to FunctionTools and to local MCP servers, and they do not apply to handoffs, to hosted tools such as WebSearchTool, FileSearchTool, HostedMCPTool, CodeInterpreterTool and ImageGenerationTool, or to built-in execution tools such as ComputerTool, ShellTool, ApplyPatchTool and the legacy LocalShellTool. Agents-as-tools do not support tool guardrails directly either. Coverage gaps need compensating controls, which in practice means approvals.

A test harness. ScriptedModel fixtures so every team can assert loop behaviour offline, plus the tool.__wrapped__ attribute, which exposes the original callable for unit tests — bearing in mind that calling it skips validation, guardrails and tracing, so it tests your logic and not your policy.

The review checklist

Use this on pull requests that add or change an agent. Each line maps to a failure described above.

Loop and budget. model set explicitly. max_turns set explicitly and justified. max_turns=None only in a controlled batch path. reset_tool_choice left at True unless there is a written reason. ModelSettings.timeout set. A retry policy with jitter present.

Errors. error_handlers cover max_turns and model_refusal at minimum. No code path assumes an empty final_output means a refusal. Truncated-response handling considered, since failed and incomplete now raise.

Tools. Authorisation enforced inside every tool body, not only via is_enabled. Side-effecting tools require approval or carry a documented exemption. Async tools that can hang have a timeout and a deliberate timeout_behavior. max_function_tool_concurrency set where tools hold scarce resources. No ShellTool or ApplyPatchTool without an exemption, and never with their default needs_approval=False.

State. Exactly one of session or server-managed conversation state per call. Output guardrails not combined with conversation_id, previous_response_id or auto_previous_response_id. Session ID derived from an authenticated principal. Production session backend, not SQLiteSession. Owned clients closed.

Approvals. Snapshots stored server-side only. Reviewer authenticated from middleware. Pending items read from server-owned state. Consumption atomic and single-use. No secrets in context. Version markers stored beside each snapshot.

Guardrails. Input guardrails that must prevent cost or side effects use run_in_parallel=False. Tool guardrails present on money and PII paths, with compensating approvals wherever tool guardrails do not apply.

Observability. workflow_name and group_id set. trace_include_sensitive_data=False where content is sensitive. flush_traces() called in background jobs. Redaction inside your own exporter, not in a separate processor. Usage metrics emitted, including reasoning tokens.

MCP. cache_tools_list=True. Tokens scoped and passed in headers. require_approval set for side-effecting tools. MCPServerStreamableHttp or MCPServerStdio, not legacy MCPServerSse. Servers used inside async with or through MCPServerManager, or you will meet UserError: Server not initialized. Make sure you call connect() first.

Dependencies. openai-agents pinned to >=0.22,<0.23. httpx2 rather than httpx anywhere a custom client is passed. mcp version decided deliberately. Provider arguments on the AsyncOpenAI client, not on OpenAIProvider.

For design documents, add four questions: where does conversation content come to rest and under which jurisdiction; what is the cost per thousand conversations at the expected turn count; what is the blast radius of the most dangerous tool if the model is talked into calling it; and what happens to an in-flight run during a deploy.

The complete picture

Three levels, compressed into one view.

What changes at senior level is not the primitives, it is where the responsibility sits. The library deliberately declines to make several decisions for you, and each decline is a thing you own. It does not retry model calls, so reliability is yours. It does not time out model calls, so latency bounds are yours. It does not authenticate RunState, so the approval security model is yours. It does not isolate the Unix-local sandbox, so the confinement decision is yours. It does not enforce per-tenant separation, so the session and context discipline is yours. It does not budget turns, so cost is yours. None of these are gaps; they are the honest boundaries of a library that runs inside someone else's process. Reading them as a list of your obligations is the whole shift from using the tool to owning it.

Where the series leaves you

You can design an agent platform, defend its trust model in a security review, predict which component breaks first under load, cost it per thousand conversations, upgrade it across breaking minor versions without a freeze, run the incident when it misbehaves, and say clearly when the answer is Temporal, LangGraph, or a single Responses call instead.

Three directions remain. Depth means picking one of durable execution, sandboxing or realtime voice and going all the way down. Breadth means putting the agent in its place in a stack: MCP for the tool protocol, Langfuse for traces you own, LiteLLM for provider routing, FastAPI for the service shape, Vault for the keys. Evidence means evaluation: a platform without quality measurement cannot tell a cost saving from a regression, which is where RAGAS and DeepEval belong.

Then read the release notes. In a project that moves its minor number for breaking changes every few weeks, the changelog is not documentation you consult when something breaks. It is the thing that stops it breaking.

Sources

• OpenAI Agents SDK documentation
• Running agents
• Agents
• Results
• Tools
• Handoffs
• Orchestrating multiple agents
• Guardrails
• Human in the loop
• Context management
• Sessions
• Model context protocol
• Models
• Configuring the SDK
• Tracing
• Usage
• Testing
• Sandbox agents
• Sandbox clients
• Release process and breaking changes
• openai-agents on GitHub
• openai-agents releases
• openai-agents on PyPI

Senior interviews about the OpenAI Agents SDK rarely test API recall. They test whether you understand what the library declines to do, because that is where production incidents come from. Expect system design, incident response, and at least one question that is really about explaining a trade-off to someone who controls a budget.

Everything here assumes openai-agents 0.22.3 on Python 3.10 or newer.

The framing that gets you hired

Open every answer from the same base: the SDK is a library, not a server. It runs inside your FastAPI worker, your Celery task or your Temporal activity. There is no control plane, no scheduler, no daemon. State lives either in a session backend you operate or at OpenAI through the Conversations API, and you pick exactly one per call.

Say that out loud in the first thirty seconds of a design question. It immediately reframes the conversation away from "how do we deploy it" and toward the questions that actually matter: concurrency in your own process, where conversation content comes to rest, and who owns durability when a pod is rescheduled mid-run.

The second framing to have ready: the library deliberately leaves six decisions to you. It does not retry model calls unless you configure ModelSettings.retry. It does not time out model calls unless you set ModelSettings.timeout. It does not authenticate a deserialized RunState. It does not isolate the Unix-local sandbox on Linux. It does not enforce tenant separation. It does not budget turns beyond a default max_turns of 10. Every one of those is a thing you own, and naming them unprompted signals that you have run this in production rather than read about it.

System design: a support platform for twelve teams

The prompt usually arrives as something like "design an agent platform that twelve product teams will build on, handling customer support for a regional fintech."

Start with the architecture, which is shorter than the interviewer expects. Agent runs happen in an async service. Sizing comes from concurrent conversations multiplied by mean run duration, not from request rate, because a run holds a connection for tens of seconds. Sessions go in Redis or Postgres through SQLAlchemySession, never SQLiteSession, which is a development backend with no integrity protection. Conversation state and output guardrails are coupled: if you choose server-managed state via conversation_id or previous_response_id, output guardrails raise UserError, because rejected output cannot be retracted from history you do not own. Say that explicitly; it is the detail that separates someone who has read the docs from someone who has shipped.

Then move to the thing that makes it a platform rather than twelve copies of a tutorial: an internal wrapper package. It owns bootstrap() — clients, keys, trace processors — and run(), which injects platform guardrails, default ModelSettings with a timeout and a jittered retry policy, default error_handlers, workflow_name, group_id, and session construction from an authenticated principal. Teams import your package, never agents directly. Justify it with the upgrade argument: this project moves its minor version for breaking changes, and four minors landed in nine days in August 2026. Forty direct call sites means forty pull requests per upgrade.

For multi-tenancy, three mechanisms: one session ID per user or thread derived from an authenticated principal, a frozen dataclass as typed context carrying tenant, user and entitlements, and group_id plus trace_metadata for trace partitioning. Note that every agent and tool in a run must share the same context type, which is a feature — it stops a tool being reused across agents with incompatible tenancy assumptions.

For tool safety, state the rule plainly: tool arguments are model output and model output is untrusted. is_enabled controls what the model sees, not what it is allowed to do, and the same is true of MCP tool_filter. The real authorisation check goes inside the tool body. Side-effecting tools get needs_approval=True.

Close on residency, which matters for a regional fintech. Tracing exports conversation content to OpenAI by default and trace_include_sensitive_data defaults to True. If a regulator or a tenant contract requires content to stay in jurisdiction, you need trace_include_sensitive_data=False or tracing_disabled=True, a session backend in the right region, and a decision about whether server-managed conversations are acceptable at all. Add that organisations on Zero Data Retention get no OpenAI tracing whatsoever, so a self-hosted processor is the only route.

What a strong answer covers that a weak one misses. A weak answer designs a deployment. A strong answer designs a wrapper, names the session-versus-conversation-state exclusivity, and raises residency without being asked.

System design: human approval for irreversible actions

"Some agent actions move money. Design the approval flow."

The mechanics are straightforward and the security is not. Mark the tool @tool(needs_approval=True), which can also be an async callable (ctx, params, call_id) -> bool if approval is conditional. The run pauses, result.final_output is None, and result.interruptions holds ToolApprovalItem objects with .name, .arguments and .agent. You take state = result.to_state(), call state.approve(item) or state.reject(item, rejection_message="..."), and resume with await Runner.run(agent, state) using the original top-level agent — approvals raised inside a nested as_tool call or after a handoff surface on the outer run.

result = await Runner.run(agent, "Refund order 42")
while result.interruptions:
    state = result.to_state()
    for item in result.interruptions:
        state.approve(item)            # or state.reject(item, rejection_message="...")
    result = await Runner.run(agent, state)

Now the part the question is actually testing. Persisting a pause means state.to_json() or state.to_string(), restored with await RunState.from_json(agent, data). Deserialization performs no authentication. Hand it any snapshot and it faithfully reconstructs the pending tool calls it will execute. So: snapshots live in server-side storage keyed by an opaque ID, never round-trip through a client; the reviewer is authenticated and authorised from session middleware, never from the request body; the pending items come from the server-owned state, not the request; and consumption is atomic and single-use so a replayed request cannot resume the same snapshot twice. No secrets go in context, because context is serialized into the snapshot.

Two more points worth volunteering. Approval callables fail closed: malformed arguments, or arguments that are not a JSON object, require manual approval rather than passing. And when approvals can wait days, store an SDK version marker and an agent-definition marker alongside each snapshot, then decide explicitly what happens when a snapshot outlives a deploy — refusing with a clear message is usually right.

Finally, note that an approval is a human gate, not a sandbox. ShellTool and ApplyPatchTool default to needs_approval=False, and even with approval on, isolation is your executor's job.

What a strong answer covers that a weak one misses. A weak answer describes the approve loop. A strong answer says "from_json does not authenticate" in the first minute and builds the storage model around that.

Incident: cost tripled overnight

Work the funnel in order, out loud.

First, turns per run. A turn is one model call, not one user message, and max_turns defaults to 10, so a badly specified agent can cost ten times what a good one does for the same question. Pull result.context_wrapper.usage.requests and compare the distribution to last week. The classic cause is a tool whose output invites an identical re-call, or tool_choice="required" with reset_tool_choice=False, which tells the model it must call a tool every turn forever. Mitigate by capping max_turns; fix by changing instructions or the tool's output.

Second, reasoning tokens. usage.output_tokens_details.reasoning_tokens is output you pay for and never see. Someone raising reasoning effort is invisible in diffs that reviewers skim.

Third, model drift. If an agent has no explicit model=, precedence falls through RunConfig.model, then the OPENAI_DEFAULT_MODEL environment variable, then the SDK default — and the SDK default has changed twice recently, to gpt-5.4-mini in 0.16.0 and to gpt-5.6-luna in 0.20.0. A dependency bump can silently change your model, your latency and your bill.

Fourth, context growth. Input tokens per turn climb as history accumulates, and that cost compounds across every turn. The levers are RunConfig(session_settings=SessionSettings(limit=N)), a session_input_callback, call_model_input_filter, ModelSettings(truncation="auto"), server-side context_management compaction, or OpenAIResponsesCompactionSession.

Fifth, guardrail mode. Input guardrails run in parallel with the agent by default, so a tripped guardrail may have already spent tokens and run tools. If the guardrail exists to prevent expense, it needs @input_guardrail(run_in_parallel=False).

What a strong answer covers that a weak one misses. A weak answer reaches for a cheaper model. A strong answer establishes that cost is a turn-count problem before it is a model-price problem, and names reasoning tokens.

Incident: latency regression with no deploy

Two suspects, and they are checkable in minutes.

Input tokens per turn is the first. Nothing deployed, but history grew, so every turn carries more context. Compaction or a session limit fixes it.

The second is MCP. Every run calls list_tools() on every attached server, so an MCP server that got slower puts its latency on the critical path of every single run — including runs that never use its tools. cache_tools_list=True removes the per-run call, with invalidate_tools_cache() for genuine changes. MCPServerManager lifecycle timeouts default to ten seconds, which is a long time to spend before failing.

A third, if you use the Responses websocket transport: each connection handles one response at a time and is capped at sixty minutes, so queueing behind an in-flight response looks exactly like latency.

Incident: a tool ran that should not have

Reconstruct from traces first: which agent, what arguments, which turn. Then ask the structural question, because it has the same answer most of the time. Was the control an is_enabled callback rather than a check inside the tool body? is_enabled hides a tool from the model. It does not prevent the tool from running. If that was the only control, the incident was waiting to happen and the fix is an in-tool authorisation check plus a tool input guardrail.

Then check coverage gaps, which is a detail worth knowing cold. Tool guardrails apply to FunctionTools and to local MCP servers. They do not apply to handoffs, to hosted tools — WebSearchTool, FileSearchTool, HostedMCPTool, CodeInterpreterTool, ImageGenerationTool — or to built-in execution tools: ComputerTool, ShellTool, ApplyPatchTool and the legacy LocalShellTool. Agents-as-tools do not support tool guardrails directly either. Where guardrails cannot reach, approvals are the compensating control.

One more: for handoffs with an input_type, the authorisation goes inside on_handoff and raises on failure. And note that handoff_filters.remove_all_tools removes tool calls from handed-off history but does not redact anything from what remains, so a specialist can still see a card number that appeared earlier. Redaction needs a custom input_filter over HandoffInputData.

Incident: approvals and runs disappear during a deploy

The honest answer starts by conceding the architecture. The loop is in-memory and in-process. If the process dies mid-run, the run is gone, along with any local tool side effects that already committed. The SDK provides no durability of its own.

That leaves two routes and you should price both. Route one: serialize RunState into your own database at every pause and rebuild the orchestration — restarts, timers, retries — yourself. Route two: adopt a durable execution engine, and the SDK ships integrations for Temporal, Dapr, Restate and DBOS. For anything with more than one human gate, route two is cheaper within a quarter.

Arguing a trade-off to leadership

Three scripts worth rehearsing, because the phrasing matters more than the technical content.

Pinning the version. "This dependency moves its minor version number for breaking changes, and four of those shipped in nine days in August. One of them changed the HTTP layer from httpx to httpx2 and would have broken every service that passes a custom client. I want us pinned to >=0.22,<0.23 and I want a scheduled day per quarter to move the pin, tested against a scripted-model suite so we are not debugging it in production." The frame is a known, budgeted cost replacing an unknown, unbudgeted one.

Explicit models everywhere. "The SDK's default model changed twice this year. Any agent of ours without an explicit model will silently change behaviour and price the next time we bump a dependency. Setting it explicitly costs one line per agent." Nobody argues with that once the mechanism is on the table.

The wrapper package. Do not sell it as architecture. Sell it as the thing that made the previous two items a one-line change instead of a forty-file change, and as the place where security's requirements are enforced rather than documented. If you need a number, use the count of direct Runner.run call sites in your codebase: that is the cost of every future policy change.

Blocking guardrails. This one needs the exchange rate, not an argument. Measure the latency a blocking guardrail adds and the tokens it saves on tripped requests, and present both. "It adds 300ms to every request and saves the full cost of the 2% that trip" is a decision leadership can make. "Guardrails should block" is not.

Questions to expect, with the short answers

"When would you not use this SDK?" If the agent is one model call with a schema, call the Responses API directly and skip the runtime. If you need a graph you can draw, version and reason about statically with conditional edges, use LangGraph. If the workflow is a DAG of deterministic steps with one model call, it belongs in Prefect or Airflow. If it runs for days with human gates, use Temporal. If you need genuine multi-provider parity, note that a long list of features is Responses-only — ToolSearchTool, tool_namespace(), defer_loading=True, ProgrammaticToolCallingTool, allowed_callers, tool_choice="programmatic_tool_calling" — and hosted tools need OpenAI Responses models. If you need browser voice, Python's realtime support is server-side WebSocket only, with no browser WebRTC transport.

"Handoff or agent-as-tool?" Handoff moves control and the conversation to the specialist, and result.last_agent becomes the specialist. Agent-as-tool keeps the orchestrator in control; the nested run gets generated input and does not inherit the parent conversation unless you pass the same session. Customer-facing routing wants handoffs. One agent owning the final answer wants as-tool.

"Is the sandbox safe?" Not uniformly. The Unix-local client provides no OS confinement on Linux, and on macOS it gives filesystem restrictions through sandbox-exec with no network isolation. For untrusted input, Docker — optionally with networking disabled — or a hosted provider such as E2B, Modal, Daytona, Runloop, Vercel, Cloudflare or Blaxel. Also, since 0.17.0 LocalFile.src and LocalDir.src must sit inside the process base directory unless granted via Manifest(extra_path_grants=...), and those grants must come from trusted config, never from model output.

"Traces are missing from our Celery workers." BatchTraceProcessor exports in the background, so a worker that exits promptly loses the batch. Call flush_traces() after the trace() block closes. If traces are missing everywhere, check for a ZDR org, OPENAI_AGENTS_DISABLE_TRACING=1, or tracing_disabled. A non-fatal Tracing client error 401 or OPENAI_API_KEY is not set, skipping trace export points at the tracing key rather than the model key, which is common when models come from a non-OpenAI provider.

"How do you guarantee redaction?" Put the redaction inside your own exporter. A separate redacting processor that fails does not stop the other processors from exporting. Also keep OPENAI_AGENTS_DONT_LOG_MODEL_DATA and OPENAI_AGENTS_DONT_LOG_TOOL_DATA at their default 1, and remember trace_include_sensitive_data is a separate control that defaults to True.

"What broke in 0.22.0?" OpenAIProvider now raises UserError when openai_client is combined with api_key, base_url, websocket_base_url, organization or project — move those onto the AsyncOpenAI client. A non-streaming Responses call ending failed or incomplete now raises ModelBehaviorError, matching streaming. Output guardrails blocking terminal tool output replace the stored output with placeholder text, customisable via RunConfig.output_guardrail_blocked_message. Each to_state() checkpoint owns an independent usage snapshot. And Agent.clone() is a shallow copy, so list attributes you do not override stay the same list object.

The ninety-second self-test

Answer these without looking. If one stalls, that is your revision topic.

Where does the agent loop run, and what happens to it during a deploy? What are the six decisions the SDK leaves to you? What does is_enabled control and what does it not? What does RunState.from_json not do? Which two state strategies are mutually exclusive, and which feature does the server-managed one remove? What is a turn, and what does max_turns default to? When do input guardrails run relative to the agent, and how do you change that? Which tool kinds do tool guardrails not cover? What does cache_tools_list=True save you? Which version introduced ModelRefusalError, and what did refusals look like before it? Where should a secret never go, and why? What is the one request type the SDK retries without being asked?

The last one is conversation_locked. Everything else fails the run unless ModelSettings.retry is configured — and that single fact, delivered unprompted, tells an interviewer more about your production experience than any architecture diagram.

These are the traps that only surface once the SDK is carrying other teams' traffic, plus the habits and checklists that stop them recurring. Written against openai-agents 0.22.3 on Python 3.10 or newer.

Traps that only appear at scale

The default model is not a constant. An agent without an explicit model= resolves through RunConfig.model, then the OPENAI_DEFAULT_MODEL environment variable, then the SDK default — and that default moved to gpt-5.4-mini in 0.16.0 and to gpt-5.6-luna in 0.20.0. The symptom is a behaviour and cost change nobody can trace to a commit, because the commit was a dependency bump. Set model explicitly on every production agent and make it a lint rule.

Nothing is retried. The SDK does not retry model calls at all unless ModelSettings.retry is set. The single exception is conversation_locked. At ten runs an hour you never notice. At ten thousand, a provider's 0.1% error rate is ten failed conversations an hour, each one losing whatever tokens the run had already spent. Configure a policy with jitter, because without jitter a provider incident synchronises every worker onto the same retry schedule.

Nothing times out either. No ModelSettings.timeout means a slow model call is unbounded, which in a FastAPI service means a held worker. If ModelTimeoutError has never appeared in your logs, you do not have timeouts; you have patience.

Tool concurrency is unbounded. Local tools in a turn run concurrently with no limit. A model emitting eight parallel calls to a tool that opens a database connection gives you eight connections from one turn, and a fan-out across concurrent runs multiplies that. RunConfig(tool_execution=ToolExecutionConfig(max_function_tool_concurrency=4)) bounds it. This is not the same knob as ModelSettings(parallel_tool_calls=...), which governs whether the model emits parallel calls at all.

MCP list_tools() runs every single run. Per server, per run, whether or not the run uses the server's tools. Four servers at a thousand runs an hour is four thousand pointless round trips, and any one of those servers getting slow puts its latency on every run's critical path. cache_tools_list=True, plus invalidate_tools_cache() when a server genuinely changes.

Input guardrails have already spent money when they trip. They run in parallel with the agent by default. Lower latency, but the agent may have spent tokens and executed tools before the tripwire cancels it. If the guardrail exists to prevent expense or an irreversible action, it must be @input_guardrail(run_in_parallel=False). Output guardrails have no such option; they always run after the agent finishes.

Output guardrails and server-managed state are incompatible. Combining an output guardrail with conversation_id, previous_response_id or auto_previous_response_id raises UserError, because rejected output cannot be retracted from history you do not own. Teams discover this after building on server-managed conversations, when compliance asks for an output filter.

session and server-managed state are also incompatible. UserError: Session persistence cannot be combined with conversation_id, previous_response_id, or auto_previous_response_id. Pick one strategy per call and enforce it in your wrapper so no call site can get it wrong.

SQLiteSession escapes into production. It has no integrity protection, and concurrency was enough of a problem that 0.22.3 shipped a fix for concurrent SQLite startup. Treat its presence outside tests as a build failure. Use RedisSession, SQLAlchemySession, MongoDBSession or a Dapr store, and close clients you own — a session is terminal after close(), and reusing it raises RuntimeError.

Agent.clone() is a shallow copy. Since 0.22.0 this is documented, and it was the behaviour people assumed otherwise. List attributes you do not override remain the same list object, so a clone that appends to tools mutates the original agent. Pass a fresh list for anything the clone should own. The bug shows up as a tool appearing on an agent that never declared it.

A stream that looks finished is not. Session writes, approval bookkeeping and compaction run after the last token, and OpenAIResponsesCompactionSession can take seconds. An HTTP handler that stops iterating stream_events() when the text looks complete silently loses history writes. Drain to completion, always.

Background jobs lose their traces. BatchTraceProcessor exports asynchronously. A Celery task, RQ job or FastAPI background task that exits promptly discards the batch. Call flush_traces() after the trace() block closes.

Redaction in a separate processor is not a guarantee. A redacting processor that fails does not stop the other processors from exporting. If redaction is a compliance requirement, it goes inside your own exporter.

Traces carry content by default. trace_include_sensitive_data defaults to True, independently of the log-redaction variables OPENAI_AGENTS_DONT_LOG_MODEL_DATA and OPENAI_AGENTS_DONT_LOG_TOOL_DATA, which default to redacting. Redacted logs with unredacted traces is a common and unintentional combination.

is_enabled is not access control. It controls what the model sees, which is good for token budget and prompt hygiene and worthless as a permission boundary. MCP tool_filter has the same property. The real check goes inside the tool body.

RunState deserialization authenticates nothing. from_json reconstructs whatever snapshot you hand it, pending tool calls included. A snapshot that round-trips through a client is a tool-argument editor.

Secrets in context leak through snapshots. Local context is never sent to the model, which makes it feel safe. It is serialized into RunState. Tenant IDs yes, credentials no.

ShellTool and ApplyPatchTool default to no approval. needs_approval=False is the default on both. Override it in your platform wrapper on day one.

The Unix-local sandbox is not a sandbox on Linux. No OS confinement. On macOS it is filesystem restrictions via sandbox-exec, with no network isolation. Untrusted input requires Docker or a hosted provider.

remove_all_tools does not redact. It strips tool calls from handed-off history. Everything else remains visible to the specialist. Redaction needs a custom input_filter over HandoffInputData.

A refusal is now an exception. Since 0.15.0, model refusals raise ModelRefusalError with .refusal. Inherited code checking if not result.final_output is testing for a condition that no longer occurs.

Truncated responses now raise too. Since 0.22.0 a non-streaming Responses call ending failed or incomplete raises ModelBehaviorError, matching the streamed behaviour. Code that quietly accepted a short answer now gets an exception, usually when max_output_tokens is hit.

reset_tool_choice=False with tool_choice="required" is an infinite loop. It tells the model it must call a tool on every turn, forever, until MaxTurnsExceeded. The default True exists to prevent exactly this.

max_turns=None in a user-facing path. It disables the turn limit entirely. Appropriate in a controlled batch job; close to negligent anywhere a user can influence the input.

Config dict typos used to be silent. Since 0.19.0 an unknown key in a ModelSettings or RunConfig dict raises TypeError instead of being ignored. That is an improvement, and it also means dict-based config written before 0.19 may fail on upgrade where it previously ran with a setting quietly absent.

Platform-ownership habits

Wrap the SDK in one package. A bootstrap() for clients, keys and trace processors, and a run() that injects platform guardrails, default ModelSettings, default error_handlers, workflow_name, group_id and session construction from an authenticated principal. Teams import your package, never agents directly. The payoff is the next minor version: one file instead of forty.

Pin, then schedule the bump. openai-agents~=0.22.3 or >=0.22,<0.23. The project moves its minor number for breaking changes to non-beta public APIs, and patch releases can change beta features — so if you use sandbox agents or nest_handoff_history, read patch notes too. Put a quarterly day on the calendar for moving the pin.

Build a scripted-model suite before you need it. agents.testing arrived in 0.21.0 and is not exported from top-level agents. ScriptedModel plus assistant_message lets you assert loop behaviour with no model call, which turns upgrade testing into CI. Note tool.__wrapped__ exposes the original callable for unit tests, but calling it skips validation, guardrails and tracing — it tests your logic, not your policy.

import pytest
from agents import Agent, RunConfig, Runner
from agents.testing import ScriptedModel, assistant_message

@pytest.mark.asyncio
async def test_platform_defaults_applied():
    model = ScriptedModel([[assistant_message("ok")]])
    agent = Agent(name="Probe", model=model)
    result = await Runner.run(agent, "ping", run_config=RunConfig(tracing_disabled=True))
    assert result.final_output == "ok"
    model.assert_complete()

Keep an agent registry. One data file listing every agent with an owner, an explicit model, an explicit max_turns, a cost budget, its approval-gated tools and a review date. Generate a page from it. This is what answers "which agents can move money" in seconds, and it is the artefact that makes security and finance conversations short.

Emit usage as metrics, tagged. result.context_wrapper.usage gives requests, input_tokens, output_tokens, total_tokens, request_usage_entries, input_tokens_details.cached_tokens and cache_write_tokens, and output_tokens_details.reasoning_tokens. Tag by tenant, agent and workflow. Three charts earn their keep: turns per run at p50/p95/p99, reasoning tokens as a share of output tokens, and cache hit rate. ModelSettings(preserve_raw_usage=True) keeps provider raw usage for invoice reconciliation, and LiteLLM or Any-LLM streaming may need include_usage=True to report at all.

Treat the p99 turn count as your headline number. Cost is a turn-count problem before it is a model-price problem. The same question costs four times as much over four turns as over one.

Separate the tracing key from the model key. set_tracing_export_api_key(...), with use_for_tracing=False when you set the model client. Different scope, different rotation schedule, revocable without taking inference down. Never pass include_tracing_api_key=True when serializing RunState unless you have a specific reason.

Tier your tool library. Read-only tools open to all; side-effecting tools behind an entitlement and needs_approval; a small privileged tier requiring a written platform exemption. Tool input and output guardrails on anything touching money or personal data, and approvals wherever guardrails cannot reach.

Know the guardrail coverage gap by heart. Tool guardrails apply to FunctionTools and local MCP servers. They do not apply to handoffs, to hosted tools (WebSearchTool, FileSearchTool, HostedMCPTool, CodeInterpreterTool, ImageGenerationTool) or to built-in execution tools (ComputerTool, ShellTool, ApplyPatchTool, legacy LocalShellTool). Agents-as-tools do not support them directly. Every gap needs a compensating approval.

Publish the handoff graph. draw_graph from the [viz] extra, run in CI for every registered multi-agent system, with the output as a build artifact. Routing bugs live in graphs nobody looks at.

Version-mark every persisted snapshot. An SDK version and an agent-definition version stored beside each serialized RunState, with an explicit policy for snapshots older than the current code. Refusing with a clear message is almost always better than resuming against changed behaviour.

Prefer the current spellings. MCPServerStreamableHttp or MCPServerStdio, not legacy MCPServerSse — the MCP project deprecated the SSE transport. ShellTool, not the legacy LocalShellTool. prompt_cache_options for GPT-5.6, not the legacy prompt_cache_retention. @tool from agents.decorators is the style the current docs use, though @function_tool is not deprecated. One exception: the streamed event name handoff_occured is misspelled deliberately for backward compatibility. Do not fix it.

Remember which SDK you are reading about. OpenAI also ships a JavaScript/TypeScript SDK with different APIs. The Python result object has final_output, not output. Snippets found online mix the two freely.

Pull request checklist

Keep this short enough that reviewers use it, and move anything mechanical into a wrapper assertion or a lint rule.

• model set explicitly. max_turns set explicitly and justified; max_turns=None only on a controlled batch path.
• ModelSettings.timeout set. A retry policy present, with jitter.
• reset_tool_choice left at True, or a written reason in the diff.
• error_handlers cover max_turns and model_refusal. No code path treats an empty final_output as a refusal.
• Authorisation enforced inside every tool body, not only through is_enabled.
• Side-effecting tools require approval, or carry a documented exemption.
• Async tools that can hang have a timeout and a deliberate timeout_behavior.
• max_function_tool_concurrency set where tools hold scarce resources.
• No ShellTool or ApplyPatchTool without an exemption, and never at their default needs_approval=False.
• Exactly one of session or server-managed conversation state per call.
• Output guardrails not combined with conversation_id, previous_response_id or auto_previous_response_id.
• Session ID derived from an authenticated principal; production backend, not SQLiteSession; owned clients closed.
• Snapshots server-side only, consumed atomically, with version markers and no secrets in context.
• Guardrails that must prevent cost or side effects use run_in_parallel=False.
• workflow_name and group_id set; flush_traces() in background jobs; trace_include_sensitive_data=False where content is sensitive.
• MCP servers used inside async with or through MCPServerManager, with cache_tools_list=True, scoped tokens in headers, and require_approval on side-effecting tools.
• Dependency pin unchanged, or the bump has its own PR with the scripted-model suite green.
• Agent.clone() calls pass fresh lists for anything the clone mutates.

Design document checklist

Four questions, asked of every design that puts an agent in a user path.

Where does conversation content come to rest, and under whose jurisdiction? Enumerate every resting place: the session store, OpenAI traces, each third-party processor, and your own application logs. For Gulf and Egyptian employers with residency obligations this is the question that decides the architecture, not a compliance footnote. Note that ZDR organisations get no OpenAI tracing at all, so a self-hosted processor is the only observability route.

What is the cost per thousand conversations at the expected turn count? Not per token. Per conversation, at the p95 turn count, including reasoning tokens. If the design cannot produce that number, it is not finished.

What is the blast radius of the most dangerous tool if the model is talked into calling it? Tool arguments are model output and model output is untrusted. The answer must be a bound, not a reassurance about the prompt.

What happens to an in-flight run during a deploy? The loop is in-process and in-memory. Either the design serializes RunState and can resume, or it accepts losing runs, or it delegates to Temporal, Dapr, Restate or DBOS. "We drain" is an acceptable answer only when no run can wait on a human.

Add a fifth if the design involves more than two agents: is this orchestration the model's job or your code's? Handoffs and agents-as-tools let the model decide, which is flexible and non-deterministic. Chaining in Python, asyncio.gather fan-out and evaluator loops are deterministic and testable. Choosing the model's judgement for something a conditional would handle is the most common over-engineering in this space, and the cheapest to catch in review.

The habit underneath all of them

Every trap on this page is the same trap seen from a different angle: a default chosen for a demo, inherited by production. Ten turns, no retries, no timeouts, unbounded concurrency, parallel guardrails, tracing with content, SQLite sessions, no approval on shell access. None of them are wrong defaults for someone learning the library. All of them are wrong for a platform.

So the habit is this: for every default the SDK gives you, decide once, write it into the wrapper, and assert it in CI. Then read the release notes before each bump, because in a project that moves its minor number for breaking changes every few weeks, the changelog is not reference material. It is the control.