OpenAI Agents SDK

Overview

The OpenAI Agents SDK is an open-source library from OpenAI for building agent applications in Python and TypeScript. It deliberately keeps the number of ideas small. You define agents, give them tools, let them hand work to each other, wrap them in guardrails, and run them with a runner that loops until there is a final answer. Tracing records every step so you can see what happened.

The design goal is "few primitives, plain code". There is no graph language to learn and no large class hierarchy. An agent is a model plus instructions plus tools. Orchestration is ordinary Python or TypeScript, or the model's own choice of which agent to hand off to.

An everyday comparison is a small clinic. The receptionist (a triage agent) listens to the patient and sends them to the right specialist (a handoff). Each specialist has their own instruments (tools). A nurse checks every request before it reaches a doctor (an input guardrail) and checks every prescription before it leaves (an output guardrail). The patient file (a session) follows the patient between visits, and the clinic log (tracing) records who did what.

What it is

The SDK is a lightweight framework around model calls and tool calls. It is published as openai-agents for Python and as the openai-agents-js project for TypeScript. The Python repository is MIT-licensed.

In Python, a function becomes a tool through the @function_tool decorator, which builds the argument schema from type hints and the docstring. In TypeScript, tool parameters are described with Zod schemas. Hosted tools such as web search and file search run on OpenAI's side. MCP servers can also supply tools, so an agent can reach any system that has an MCP server.

Where it came from

In October 2024 OpenAI published Swarm, an experimental, educational library that showed how agents could hand conversations to each other. It was explicitly not meant for production. In March 2025 OpenAI released the Agents SDK as its production-ready successor, at the same time as the Responses API and new hosted tools for web search, file search and computer use. The SDK kept Swarm's simple idea of handoffs and added guardrails, tracing and better typing.

A TypeScript version followed later in 2025 with a similar surface. Over time the SDK added sessions for conversation memory, MCP support, voice and realtime agents, and more ways to plug in other model providers. By default it uses OpenAI's Responses API, but it also supports the Chat Completions style of API and, through adapters such as LiteLLM, models from other providers.

How it works

Step 1: Define agents

You create one or more agents. Each has a name, instructions (its system prompt), a model, tools, a list of agents it may hand off to, and optionally an output type. A triage agent might know about three specialists.

Step 2: Start a run

You call the runner with a starting agent and an input. Runner.run() is asynchronous, Runner.run_sync() blocks, and Runner.run_streamed() streams events as they happen.

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
result = Runner.run_sync(agent, "Explain what a handoff is in one sentence.")
print(result.final_output)

Step 3: The loop

The runner calls the model for the current agent. Three things can happen:

• The model returns a final output. If the agent has an output type, the output must match it. The run ends.
• The model calls a tool. The runner executes it, adds the result to the conversation and loops.
• The model calls a handoff. Control moves to the new agent, which sees the conversation so far, and the loop continues.

A max_turns limit stops runaway loops by raising an error.

Step 4: Guardrails run alongside

Input guardrails check the first agent's input. They can run in parallel with the agent to save time, or block until they finish. Output guardrails check the final output. Tool guardrails wrap function-tool calls. Each guardrail returns a result with a tripwire flag. If the tripwire is set, the run stops with an exception that your code can catch. A guardrail can itself be a small, cheap agent, for example one that decides whether a message is off-topic.

Step 5: Sessions and context

Without a session, you pass previous messages yourself. With a session, such as the SQLite-backed one, the SDK stores and reloads history automatically, so the next run continues the conversation. You can also pass a typed context object to tools for things like the current user ID or a database client. This context is for your code; it is not sent to the model.

Step 6: Tracing

Every run produces a trace made of spans: model calls, tool calls, handoffs and guardrail checks. By default traces go to the OpenAI dashboard. You can add trace processors to send them to other backends, or turn tracing off. See tracing for the general idea.

Key concepts and terms

A worked example

This scenario is illustrative. An online shop builds a support assistant.

1. A triage agent reads each message. It can hand off to three specialists: orders, returns and billing.
2. The orders agent has a function tool get_order_status(order_id) that queries the shop's database through a typed context holding the customer ID.
3. The returns agent has a tool that creates a return label, but only after a human-in-the-loop approval step in the shop's own code for orders above 200 euros.
4. An input guardrail, run by a small model, flags messages that ask for another customer's data. When it trips, the app replies with a fixed refusal.
5. An output guardrail checks that replies never include full card numbers.
6. A SQLite session keeps each customer's thread.

In a test of 500 past tickets, the team reads traces for every ticket the triage agent routed to the wrong specialist. They find 31 such cases, most about delivery address changes. They update the triage instructions with two examples and re-run the same 500 tickets to check the fix did not break anything else.

Strengths and limitations

Strengths:

• Very small set of concepts that are quick to learn.
• Handoffs make multi-agent routing simple and readable.
• Guardrails are first-class and can run in parallel to reduce latency.
• Built-in tracing with no extra setup.
• Python and TypeScript versions with similar designs.
• Works with OpenAI's hosted tools and with MCP servers.

Limitations:

• The smoothest path assumes OpenAI models and the Responses API; other providers can lose some features.
• Default tracing sends data to OpenAI, which some organisations must disable or redirect.
• No built-in durable execution: a long job that crashes mid-run needs your own recovery.
• Handoff-based routing can loop or bounce between agents if instructions overlap.
• Few built-in local tools such as file editing or shell access.

How it compares with alternatives

Practical guidance and best practices

1. Start with one agent and add handoffs only when instructions become crowded.
2. Write clear, non-overlapping handoff descriptions so the model routes reliably.
3. Use an output type when another program will consume the result.
4. Put cheap, fast checks in parallel input guardrails; keep expensive checks for output.
5. Set max_turns deliberately and handle the error it raises.
6. Keep side-effecting tools behind approval in your own code.
7. Decide early where traces may be stored, and redact sensitive fields.
8. Re-run a fixed set of real conversations as evals after every prompt or tool change.

Common mistakes

• Using handoffs where an "agent as tool" call would keep control in one place.
• Giving every agent every tool, which confuses tool choice.
• Treating guardrails as complete security instead of one layer; see guardrails.
• Forgetting that the context object is not visible to the model and expecting the model to "know" it.
• Leaving default tracing on for data that must not leave your environment.
• Building long workflows without a way to resume after failure.

Frequently asked questions

What is the OpenAI Agents SDK?

It is OpenAI's open-source Python and TypeScript framework for building agent apps from a few primitives: agents, tools, handoffs, guardrails, sessions and tracing, driven by a runner loop.

How is it related to Swarm?

Swarm was an experimental library released in October 2024 to teach handoff-based multi-agent design. The Agents SDK, released in March 2025, is the production successor that keeps handoffs and adds guardrails, tracing and typing.

Can I use models from other providers?

Yes, within limits. The default path uses OpenAI's Responses API, but the SDK can use Chat Completions-style endpoints and adapters such as LiteLLM. Some hosted tools and features only work with OpenAI models.

What is the difference between a handoff and an agent used as a tool?

A handoff passes control to another agent, which then talks to the user. An agent used as a tool runs, returns its answer to the calling agent, and the caller stays in charge.

Does it support MCP?

Yes. Agents can use tools provided by MCP servers, as well as local function tools and OpenAI's hosted tools.

Do I need tracing?

You do not have to keep it, but it is the fastest way to debug routing and tool errors. You can disable it or send traces to your own backend.

Glossary

• Agent: a configured model with instructions and tools.
• Handoff: transfer of control to another agent.
• Guardrail: a check that can halt a run.
• Tripwire: the signal that a guardrail has failed.
• Runner: the loop that executes agents.
• Session: stored history across runs.
• Span: one recorded step inside a trace.
• Output type: a schema for the final answer.
• Hosted tool: a tool executed by OpenAI's platform.

Summary

The OpenAI Agents SDK builds agent apps from a handful of primitives: agents, tools, handoffs, guardrails, sessions and tracing. It grew out of the Swarm experiment and became OpenAI's production framework in March 2025. It is quick to learn and strong for routing and guarded conversations, but it leaves durable execution and many local tools to you. Keep agents focused, write clear handoff descriptions, guard side effects, and test against real conversations.

Related

It belongs to Agent SDKs in my stack, under Agentic AI. Others in the same group: