The OpenAI Agents SDK (open-source, Python) provides a lightweight, opinionated framework for building production agents with four core primitives: Agents, Handoffs, Guardrails, and Tracing. Unlike heavier frameworks, it embraces minimal abstraction — just enough structure to build reliable multi-agent systems without hiding the underlying mechanics.
| Primitive | Purpose | Key Concept |
|---|---|---|
| Agent | A configured LLM with instructions, tools, and model | The basic unit — wraps a system prompt + tool set |
| Handoff | Transfer control from one agent to another | Triage agent routes to specialized agents (billing, support, etc.) |
| Guardrail | Input/output validation that runs in parallel with the agent | Catches policy violations, PII leaks, or off-topic responses before they reach the user |
| Tracing | Built-in observability for every agent run | Automatic logging of LLM calls, tool executions, handoffs, and guardrail checks |
The Handoffs pattern is the SDK's signature feature. A triage agent evaluates the user's request and hands off to a specialist agent with full context transfer:
from agents import Agent, handoff, Runner
billing_agent = Agent(
name="Billing Specialist",
instructions="Handle billing inquiries. Access the billing database.",
tools=[lookup_invoice, process_refund]
)
tech_agent = Agent(
name="Technical Support",
instructions="Debug technical issues. Access logs and documentation.",
tools=[search_docs, check_status]
)
triage_agent = Agent(
name="Triage",
instructions="Route the customer to the right specialist.",
handoffs=[handoff(billing_agent), handoff(tech_agent)]
)
# Agents-as-Tools: use an agent as a tool (returns result to caller)
triage_agent_v2 = Agent(
name="Coordinator",
tools=[billing_agent.as_tool(), tech_agent.as_tool()]
)
result = await Runner.run(triage_agent, "I was double-charged")
# → Triage hands off to Billing Specialist automatically
Guardrails run in parallel with the agent. If a guardrail trips, the agent's response is blocked before reaching the user:
| Pattern | Control Flow | Best For |
|---|---|---|
| Handoff | Control transfers TO the new agent (caller loses control) | Full delegation — "you handle this" |
| Agent-as-Tool | Caller invokes agent, gets result back | Sub-task — "do this and report back" |