Area 03 · AI Agents · Concept 14 of 20

OpenAI Agents SDK

A light framework for agents with tools, handoffs, guardrails and tracing built in.

11–20 · Production levelPhase 3 · Weeks 11–14≈ 1.5 hours

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.

Why it matters

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

  1. Run the code example with an OpenAI key.
  2. Open the traces view in the OpenAI dashboard.
  3. Find each tool call and its duration.

Use it in code

An agent with a function tool and an output type.

python
# 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)
PRACTICE · TICK IT AFTER THIS

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.

Go deeper