The OpenAI Agents SDK is a lightweight Python framework for building agents with a small set of primitives: an Agent (a model plus instructions and…
See the SDK's lightweight, primitives-first philosophy.
The OpenAI Agents SDK is a small, production-minded framework for building agents in Python. Rather than a large abstraction, it offers a handful of composable primitives — agents, tools, handoffs, guardrails, and sessions — plus a runner that executes the agent loop. It is the successor to the earlier experimental Swarm project, hardened for real use.
The design bet is that a few clear primitives beat heavy machinery: you can read what the agent does, and there's little hidden behavior. It works with OpenAI models and, through a model-agnostic interface, other providers too.
Learn the pieces you compose into an agent.
An Agent is a model plus instructions (its system prompt) and a list of tools it may call. Tools are just functions you expose, described so the model knows when to use them. Sessions add memory: attach one and the agent automatically remembers prior turns of a conversation.
You define an agent declaratively — its name, instructions, and tools — and run it on an input. The SDK handles turning your functions into tool schemas and wiring the model's tool calls back to your code.
from agents import Agent, Runner, function_tool @function_tool def get_weather(city: str) -> str: return lookup(city) agent = Agent(name="Helper", instructions="Answer using tools when helpful.", tools=[get_weather]) result = Runner.run_sync(agent, "What's the weather in Paris?") print(result.final_output)
A decorated function becomes a tool; the Agent bundles instructions and tools; the Runner executes the loop until a final answer. The SDK converts get_weather into a schema, lets the model call it, and returns the finished output.
Understand how the runner loops and how agents delegate.
The runner drives the agent loop: it sends the input to the model, and if the model requests a tool, the SDK runs it and feeds the result back, repeating until the model returns a final answer instead of a tool call. This is the standard observe-decide-act loop, handled for you with a stop when the agent is finished.
Handoffs let one agent pass control to another. Modeled as a special kind of tool call, a triage agent can hand a billing question to a billing agent and a technical one to a support agent. This is how the SDK does multi-agent work — as delegation between focused agents rather than a group chat.
Add safety and observability, and avoid the common errors.
Guardrails run checks alongside the agent — validating input before it runs or output before it's returned — and can halt the run if something is off-topic, unsafe, or malformed, giving you a safety layer without hand-wiring it. Built-in tracing records each step (model calls, tool calls, handoffs) so you can see exactly what the agent did, which is essential for debugging non-deterministic agents.
Together, a readable loop plus tracing and guardrails is what makes the SDK's few primitives production-worthy.
Watch for: vague tool descriptions so the model picks the wrong tool or none; no guardrails on untrusted input or risky output; over-splitting into many handoff agents when one agent with tools would do; and ignoring tracing when debugging. Give tools sharp descriptions, add guardrails for anything user-facing, and use traces to see why the loop did what it did.
The OpenAI Agents SDK builds agents from a few primitives: an Agent (model + instructions + tools), tools, handoffs (delegate to another agent), guardrails (validate input/output), and sessions (memory). A runner executes the observe-decide-act loop until a final answer, and built-in tracing shows every step. It's the hardened successor to Swarm and works across providers. Give tools sharp descriptions, add guardrails for user-facing input, and use traces to debug — favoring readable simplicity over heavy abstraction.
Design a support agent with the SDK: one triage agent that hands off to a billing agent and a tech agent. List each agent's instructions and tools, one input guardrail you'd add, and what you'd look for in the trace when a handoff goes to the wrong agent.
What is the OpenAI Agents SDK?
The SDK favors a small set of composable primitives over heavy abstraction; it is the hardened successor to Swarm.
What is an Agent in the SDK?
An Agent bundles a model, its instructions, and tools; the runner executes it, converting your functions into tool schemas.
What is a handoff?
Handoffs implement multi-agent delegation — e.g. a triage agent routing to a billing agent — rather than a group conversation.
What do guardrails and tracing add?
Guardrails provide a safety layer and tracing gives observability, making the SDK's simple primitives production-ready.