The OpenAI Agents SDK is an open-source framework for building agentic applications, in which a language model plans, calls tools and delegates work to other agents inside a managed loop. Among AI frameworks & tools in artificial intelligence, it sits at the lightweight orchestration layer: it does not train or serve models, but coordinates how a model, its tools and its collaborators interact during a task.
Released in 2025 as the production successor to the experimental Swarm project, the SDK is available for Python and TypeScript. Its design philosophy is deliberate minimalism: a small set of primitives (agents, tools, handoffs, guardrails, sessions and tracing) that developers combine with ordinary code instead of learning a large graph or chain abstraction.
How the agent loop in the OpenAI Agents SDK works
The SDK runs an agent loop that repeats model calls until the agent produces a final answer. A Runner sends the agent’s instructions and the conversation to the model; if the model requests a tool call, the runner executes the function, appends the result and calls the model again. If the model requests a handoff, control passes to another agent, and the loop continues with that agent’s instructions and tools.
The loop ends when the model returns output that matches the agent’s declared output type, or when a maximum turn limit is reached, which raises an exception instead of running indefinitely. Developers start a run with Runner.run for asynchronous code, Runner.run_sync for scripts, or Runner.run_streamed to receive incremental events such as token deltas, tool calls and agent switches.
The following table lists the core primitives and the role each plays in a run.
| Primitive | What it defines | Typical configuration |
|---|---|---|
| Agent | A model with instructions, tools and settings | Name, instructions, model, output type |
| Function tool | A Python or TypeScript function the model may call | Decorator that derives a JSON schema |
| Handoff | Delegation of the conversation to another agent | List of target agents with descriptions |
| Guardrail | A validation check on input or output | Tripwire that halts the run on failure |
| Session | Persistent conversation memory across runs | SQLite, Redis or a custom store |
| Tracing | A record of every step in a run | Enabled by default, custom processors |
Tools, handoffs and guardrails
Tools give an agent the ability to act, and the SDK supports three tool categories. Function tools wrap ordinary code; the SDK reads type hints and docstrings to generate the schema, and Pydantic validates the arguments. Hosted tools such as web search, file search, code interpreter and computer use run on OpenAI infrastructure. Agents as tools let one agent call another as a subroutine and receive its result without giving up control.
Handoffs differ from agents as tools in who owns the conversation afterward. With a handoff, the receiving agent takes over and answers the user directly, which suits triage patterns where a front-line agent routes requests to specialists. With an agent used as a tool, the calling agent stays in charge and merges the result into its own reasoning, which suits manager-worker patterns.
The table below compares the delegation options.
| Pattern | Who answers the user | Best suited for |
|---|---|---|
| Handoff | The receiving specialist agent | Routing by intent or language |
| Agent as tool | The original orchestrating agent | Combining several expert results |
| Code orchestration | Whatever the developer’s code decides | Deterministic pipelines and parallel runs |
Guardrails run in parallel with the agent. An input guardrail can classify the first user message, for example detecting off-topic or abusive requests, and trip a tripwire that stops the run before an expensive model completes. An output guardrail checks the final answer, for example for leaked personal data. Guardrails are ordinary agents or functions, so they can use a cheaper, faster model.
Models, tracing and the Model Context Protocol
The SDK uses the OpenAI Responses API by default and also supports the Chat Completions API. Although built by OpenAI, it is provider-agnostic in principle: a model interface and an adapter for LiteLLM allow other providers, although some features, such as hosted tools and certain structured output modes, work only with OpenAI models.
Built-in tracing records each model call, tool call, handoff and guardrail as spans within a trace. Traces appear in the OpenAI dashboard by default, and custom trace processors forward them to observability platforms such as Langfuse or LangSmith. For regulated workloads, tracing can be disabled or redirected so that prompts never leave the organization.
The SDK also acts as a Model Context Protocol (MCP) client. An agent can connect to local MCP servers over standard input and output or to remote servers over HTTP, and the server’s tools appear to the model like native function tools. This makes existing MCP integrations reusable without writing wrappers.
How it compares with other agent frameworks
The OpenAI Agents SDK competes with several orchestration frameworks, and the main difference is abstraction level. The table summarizes how it relates to its closest neighbors.
| Framework | Core abstraction | Main contrast with the Agents SDK |
|---|---|---|
| LangGraph | Explicit state graph with nodes and edges | More control over flow, more boilerplate |
| CrewAI | Role-based crews with tasks | Higher-level, opinionated team metaphor |
| AutoGen | Conversing agents and event-driven runtime | Stronger focus on multi-agent research |
| Claude Agent SDK | Agent harness with file and shell tools | Built around a coding-agent runtime |
| Pydantic AI | Typed agents with dependency injection | Similar minimalism, model-neutral by design |
In practice, teams choose the Agents SDK when they want fast prototyping with few concepts and close integration with OpenAI models, and they choose a graph framework when workflows need explicit branching, checkpoints and resumable state.
Limitations and common mistakes
The SDK keeps orchestration simple, but agent reliability still depends on the model and on how instructions and tool descriptions are written. Each loop iteration adds latency and token cost, so long tool chains become expensive quickly. The table lists frequent problems and their remedies.
| Symptom | Likely cause | Fix |
|---|---|---|
| Max turns exceeded | Tool keeps returning ambiguous results | Return clear errors, lower tool count |
| Wrong agent receives handoff | Vague handoff descriptions | Write distinct, specific descriptions |
| Malformed tool arguments | Loose type hints or missing docstrings | Use strict Pydantic models |
| Sensitive data in traces | Default tracing to the dashboard | Disable or redirect trace export |
| Lost context between runs | No session configured | Attach a persistent session store |
- Too many tools on one agent degrade selection accuracy; splitting them across specialists usually helps.
- Guardrails are not a security boundary on their own; tools that change data still need authorization checks in code.
- Non-OpenAI models may lack hosted tools or strict structured outputs, so portability should be tested, not assumed.
The short version
The OpenAI Agents SDK is a toolkit that helps programmers build AI assistants that can do things, not only talk. The assistant can look something up, run a calculation or pass the conversation to a more specialized assistant, and the toolkit handles the back-and-forth automatically.
Think of it as a small office with a receptionist. The receptionist listens, decides who should handle the request and hands it over. Rules at the door stop inappropriate requests, and a logbook records every step so that someone can later check exactly what happened.
Where it makes a difference
An online electronics retailer builds a support assistant with the SDK. A triage agent reads each message and hands off to one of three specialists: an order-status agent with a function tool that queries the order database, a returns agent that can create return labels, and a technical agent that uses file search over product manuals.
An input guardrail running on a small model blocks requests unrelated to the store before the main model is called, and a session store keeps each customer’s history between visits. During testing, the team reads traces and discovers that the returns agent loops on incomplete order numbers; returning an explicit error message from the tool fixes it.
After launch, the assistant resolves routine order and return questions without a human, while traces give the support lead a clear audit trail for every escalated case.