OpenAI Agents SDK

On this page 7

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.

PrimitiveWhat it definesTypical configuration
AgentA model with instructions, tools and settingsName, instructions, model, output type
Function toolA Python or TypeScript function the model may callDecorator that derives a JSON schema
HandoffDelegation of the conversation to another agentList of target agents with descriptions
GuardrailA validation check on input or outputTripwire that halts the run on failure
SessionPersistent conversation memory across runsSQLite, Redis or a custom store
TracingA record of every step in a runEnabled by default, custom processors
Core primitives of the OpenAI Agents SDK

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.

PatternWho answers the userBest suited for
HandoffThe receiving specialist agentRouting by intent or language
Agent as toolThe original orchestrating agentCombining several expert results
Code orchestrationWhatever the developer’s code decidesDeterministic pipelines and parallel runs
Delegation patterns compared

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.

FrameworkCore abstractionMain contrast with the Agents SDK
LangGraphExplicit state graph with nodes and edgesMore control over flow, more boilerplate
CrewAIRole-based crews with tasksHigher-level, opinionated team metaphor
AutoGenConversing agents and event-driven runtimeStronger focus on multi-agent research
Claude Agent SDKAgent harness with file and shell toolsBuilt around a coding-agent runtime
Pydantic AITyped agents with dependency injectionSimilar minimalism, model-neutral by design
Positioning against related frameworks

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.

SymptomLikely causeFix
Max turns exceededTool keeps returning ambiguous resultsReturn clear errors, lower tool count
Wrong agent receives handoffVague handoff descriptionsWrite distinct, specific descriptions
Malformed tool argumentsLoose type hints or missing docstringsUse strict Pydantic models
Sensitive data in tracesDefault tracing to the dashboardDisable or redirect trace export
Lost context between runsNo session configuredAttach a persistent session store
Frequent problems and fixes
  • 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.