GitHub shows 28,787 stars, Apache-2.0 license, Python 3.10+ — the scorecard for OpenAI's official openai-agents-python repo.
The Agent framework space is crowded: LangGraph, CrewAI, AutoGen, each with its own design philosophy. So why release another one now — hype, or substance? After reading through the code, running a demo, and comparing it side-by-side with LangGraph, the verdict is: worth spending an afternoon on.
What Problem Does It Solve
Between a multi-agent demo and production, there are several gaps:
- Tool calling: how do you let an LLM safely hit external APIs?
- Human-in-the-loop: what happens when an agent needs human confirmation mid-run?
- Session state: how do you persist context across turns?
- Observability: what actually happened inside the agent? Where are the traces?
- Guardrails: how do you validate user input and model output?
OpenAI packaged all of this engineering scaffolding into a lightweight SDK called openai-agents. pip install and you're off. No more reinventing the wheel every project.
Getting Started
Three steps to a running agent:
pip install openai-agents
# or with uv
uv add openai-agents
For voice capabilities:
pip install openai-agents[voice]
For Redis-backed session storage:
pip install openai-agents[redis]
The minimum viable hello world:
from agents import Agent, Runner, function_tool
@function_tool
def get_weather(city: str) -> str:
"""查询指定城市的天气"""
return f"{city} 今天晴,25°C"
agent = Agent(
name="WeatherBot",
instructions="你是天气助手,用户问天气就调用工具回答",
tools=[get_weather],
)
result = Runner.run_sync(agent, "北京今天天气怎么样?")
print(result.final_output)
That's it. For streaming, swap run_sync for Runner.run_streamed.
How It Works (Architecture)
The core loop is straightforward:
Agent → Runner → LLM call → tool execution → feed result back → repeat until final_output
The key modules, broken down:
- Agent: the configuration layer. Name, instructions, tools, handoffs, and
output_typeall live here. - Runner: the execution layer. Drives the entire run loop. Three entry points:
run_sync,run,run_streamed. - Session: the conversation layer. Manages history across turns, with backends for SQLite, Redis, and others.
- Trace: the observability layer. Every run auto-generates traces; the UI lives at
openai.github.io/openai-agents-python/tracing/. - Guardrail: input/output validation. Input guardrails run on user messages, output guardrails run on the final output — two-way checks.
Handoff is the most interesting mechanism in this framework — delegation between agents. At its core, the current agent hands control of its run loop over to another agent. A common pattern: a front-desk agent receives a complex request and hands off to a specialist agent.
Strengths and Weaknesses
Where It Shines
- Official backing, and it's an SDK — not a platform. Unlike LangGraph, which requires deploying Studio separately, this is just a pip package that drops into your existing codebase.
- Provider-agnostic. Native support for the OpenAI Responses API and Chat Completions, plus 100+ other LLMs via adapters like LiteLLM. You're not locked into OpenAI.
- Built-in tracing. No wiring up LangSmith or anything else — it works out of the box.
- Guardrails on both input and output. More thorough than most frameworks.
- Native HITL (Human-in-the-Loop). Mechanisms like
needs_approvalare built in directly.
Where It Falls Short
- Reliance on OpenAI's Responses API for real-time features. Other models are supported, but advanced features like Realtime Agents require OpenAI.
- Complex state machines aren't its forte. LangGraph uses a graph structure that can express any DAG; Agents SDK is fundamentally loop + handoff, with less expressive power.
- Voice / Realtime is rough outside regions with good OpenAI connectivity. Realtime Agents run on
gpt-realtime, which depends on the OpenAI Realtime API — latency and stability can be issues.
Hands-On Test
Started a project with uv init, ran uv add openai-agents, set the OPENAI_API_KEY, and ran the hello world — install to output took under 5 seconds.
Then wrote an agent with a Function Tool (the weather example above). Tool call succeeded on the first try, output matched expectations.
Compared against an equivalent LangGraph demo:
- LangGraph requires defining StateGraph, nodes, and edges — roughly 1.7x the code volume.
- But LangGraph's state management is more granular, with precise control over input/output schemas at each step.
I opened the Tracing UI and could see every run's tool calls, LLM responses, and guardrail triggers. But the full dashboard isn't available locally (the UI is hosted on GitHub Pages), which is a step behind LangSmith's local-first approach.
How It Compares
| Dimension | Agents SDK | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|
| Form factor | SDK | Framework + platform | Framework | Framework |
| State model | Loop + handoff | DAG graph | Role-based collaboration | Conversation |
| Learning curve | Low | Medium | Low | Medium |
| Tracing | Built-in | LangSmith | Third-party | Third-party |
| Best fit | Standardized toolchains | Complex workflows | Role-playing scenarios | Research |
One-line summary: lighter than LangGraph, more SDK-like than CrewAI, more production-ready than AutoGen.
Who Should Use It
Good fit:
- Teams that want to quickly build production-grade agent chains
- Projects already using the OpenAI API
- Multi-agent systems that need standardized tracing
- Small-to-medium apps that need guardrails, handoffs, and sessions out of the box
Not a good fit:
- Workflows requiring complex DAGs / state machines (use LangGraph instead)
- Fully offline / on-prem deployments (too many dependencies)
- Products that need stable Voice / Realtime in regions with limited OpenAI access
My Take
OpenAI's SDK isn't trying to replace LangGraph — it's an official option for teams already on the OpenAI API who want to bolt engineering-grade capabilities onto their agents fast. The 28k stars show the community has voted with their attention.
If you're starting fresh on agent work with no legacy baggage, this SDK offers the smoothest experience available right now. If your workflow is already a graph, don't switch just to switch.