The idea
The OpenAI Agents SDK keeps the agent loop small and Pythonic. An Agent has instructions, tools (plain Python functions with the @function_tool decorator), optional handoffs to other agents, and optional guardrails that check input or output in parallel.
Runner.run executes the loop until the agent produces a final output, handling tool calls and handoffs. Tracing is on by default, so every run is recorded with its steps, tool calls and timings.
It works with OpenAI models natively and with other providers through adapters. Its value is speed of building: a working multi-agent prototype takes minutes.
It is one of the most used lightweight agent frameworks and a good contrast to graph-based LangGraph.
Words to know
- GuardrailA check that can stop a run if input or output breaks a rule.
- TraceThe recorded steps of one run.
Try it without code
Read a trace
- Run the code example with an OpenAI key.
- Open the traces view in the OpenAI dashboard.
- Find each tool call and its duration.
Use it in code
An agent with a function tool and an output type.
# pip install openai-agents
from pydantic import BaseModel
from agents import Agent, Runner, function_tool
@function_tool
def lookup_order(order_id: str) -> str:
"""Return the status of an order."""
return f"Order {order_id}: shipped yesterday, arrives Friday."
class Reply(BaseModel):
answer: str
needs_human: bool
agent = Agent(name="Support", instructions="Answer order questions briefly.",
tools=[lookup_order], output_type=Reply)
result = Runner.run_sync(agent, "Where is order A-1009?")
print(result.final_output)Port your research agent to the SDK and compare lines of code and trace quality with your hand-written loop.
Common mistakes
- Treating the framework as magic; read the trace.
- Skipping guardrails because the demo works.