TopolearnThe SDK handles the agent loop, delegation, memory and tracing, which is a lot of code you would otherwise write.
The Agents SDK (pip install openai-agents, imported as agents) is OpenAI's open-source Python library for building agents inside your own app. It runs the loop you wrote by hand in the function-calling lesson: call the model, run tools, feed results back, repeat.
Core pieces:
Agent(name=..., instructions=..., tools=[...]): a model plus its instructions and tools.Runner.run_sync(agent, input)(orawait Runner.run(...)in async code) runs the loop and returns a result withfinal_output.- Tools: plain Python functions marked with the
@tooldecorator (older examples use@function_tool); the SDK builds the schema from type hints and the docstring. Hosted tools such as web search are available too. - Handoffs:
handoffs=[other_agent, ...]lets a triage agent pass the conversation to a specialist.agent.as_tool(...)instead lets one agent call another like a function and keep control. - Sessions:
SQLiteSession("user_123")and other back ends store history so later runs remember earlier ones. - Guardrails and tracing: checks that run beside the agent (next lessons), and a record of every step you can inspect in the dashboard's trace viewer.
Which runtime to choose: the Responses API for full control; the Agents SDK when the agent runs in your app with your tools and storage; the Agents API (beta) when you want OpenAI to host a long-running agent with its own sandbox and saved sessions. The older Agent Builder is being retired in November 2026.
Example
# pip install openai-agents (uses OPENAI_API_KEY)
from agents import Agent, Runner, SQLiteSession
from agents.decorators import tool
@tool
def order_status(order_id: str) -> str:
"""Look up the shipping status of an order."""
return {"A1": "shipped", "B2": "processing"}.get(order_id, "not found")
billing = Agent(name="Billing", handoff_description="Refunds and invoices",
instructions="Help with billing questions.")
support = Agent(name="Support",
instructions="Help with orders. Hand billing questions to Billing.",
tools=[order_status], handoffs=[billing])
session = SQLiteSession("customer_42")
r = Runner.run_sync(support, "Where is order A1?", session=session)
print(r.final_output)
r = Runner.run_sync(support, "And can I get a refund for it?", session=session)
print(r.last_agent.name, "->", r.final_output) # Billing -> ...Remember
- Agent + Runner run the tool loop for you
- Handoffs transfer control; agent.as_tool keeps it
- Sessions add memory; tracing records each step
Watch out for
- Mixing up handoffs and agents-as-tools: a handoff gives the conversation away, as_tool returns to the caller.