GitHub 上 28,787 stars、Apache-2.0 協議、Python 3.10+——這是 OpenAI 官方在 openai-agents-python 這個倉庫繳出的成績單。
市面上的 Agent 框架已經夠多了:LangGraph、CrewAI、AutoGen,每家都有自己的設計哲學。OpenAI 選在這個時間點再推出一個,究竟是湊熱鬧還是真有料?我翻過一輪程式碼、跑過一遍 demo,也跟 LangGraph 做了對比,結論是:值得花一個下午試試。
它要解決的問題
多 Agent 開發從 demo 走到生產,中間隔著好幾道鴻溝:
- 工具呼叫:怎麼讓 LLM 安全地呼叫外部 API?
- 人機協作:Agent 跑到一半需要人確認怎麼辦?
- 會話狀態:多輪對話的 context 怎麼持久化?
- 可觀測性:Agent 內部到底做了什麼?trace 從哪裡看?
- 安全護欄:使用者輸入和模型輸出怎麼校驗?
OpenAI 把這些工程化能力打包成一個輕量 SDK,名字就叫 openai-agents,pip 裝一下就能用。開發者不必每次都重新造輪子。
怎麼用
三步就能跑起一個 Agent:
pip install openai-agents
# 或者用 uv
uv add openai-agents如果需要語音能力:
pip install openai-agents[voice]需要 Redis 做會話儲存:
pip install openai-agents[redis]最小可運行的 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)跑起來就這幾行。想要串流輸出,把 run_sync 換成 Runner.run_streamed 即可。
它的運作方式(架構)
核心迴圈不複雜:
Agent → Runner → LLM 呼叫 → tool 執行 → 結果回灌 → 直到 final_output關鍵模組拆開來看:
- Agent:配置層。名字、instructions、tools、handoffs、output_type 都掛在這。
- Runner:執行層。負責驅動整個 run loop,提供
run_sync、run、run_streamed三種入口。 - Session:會話層。多輪對話的 history 管理,支援 SQLite、Redis 等後端。
- Trace:可觀測層。每次 run 自動產生 trace,UI 在
openai.github.io/openai-agents-python/tracing/。 - Guardrail:輸入輸出校驗。input guardrails 跑在使用者訊息上,output guardrails 跑在 final output 上,雙向把關。
Handoff 是這套框架最值得講的機制——Agent 之間的委派。本質上是當前 Agent 把控制權交給另一個 Agent 的 run loop。常見用法是「前台 Agent 接到複雜需求 → handoff 給專家 Agent」。
它的優點與不足
優點
- 官方背書 + SDK 而非平台。不是 LangGraph 那種需要另外部署 Studio 的平台,就是一個 pip 包,跟現有程式碼融在一起。
- Provider-agnostic。原生支援 OpenAI Responses API 和 Chat Completions,也支援 100+ 其他 LLM(透過 LiteLLM 之類的適配層),不會被綁死在 OpenAI。
- Tracing 內建。不用自己接 LangSmith 或其他工具,開箱即用。
- Guardrails 採輸入輸出雙校驗。這點比多數框架想得更周全。
- HITL(Human-in-the-loop)原生支援。
needs_approval之類的機制直接內建。
不足
- 對 OpenAI Responses API 的即時功能有依賴。雖然支援其他模型,但想體驗 Realtime Agents 這類進階功能,還是得用 OpenAI。
- 複雜狀態機不如 LangGraph。LangGraph 是圖結構,能表達任意 DAG;Agents SDK 本質是迴圈 + handoff,表達力沒那麼強。
- Voice / Realtime 對國內網路不友善。Realtime Agents 用的是
gpt-realtime,依賴 OpenAI Realtime API,延遲和穩定性都是問題。
實際測試
用 uv init 起一個專案,uv add openai-agents,配好 OPENAI_API_KEY,跑 hello world——從裝套件到出結果,< 5 秒。
接著寫了一個帶 Function Tool 的 Agent(就是上面那個查天氣的),tool 呼叫一次成功,輸出符合預期。
對比 LangGraph 同等 demo:
- LangGraph 要定義 StateGraph、節點、邊,程式碼量約是這個的 1.7 倍。
- 但 LangGraph 的狀態管理更細,能精確控制每一步的輸入輸出 schema。
Tracing UI 我點開看了,能看到每次 run 的 tool 呼叫、LLM 回應、guardrail 觸發情況。不過本地看不到完整 dashboard(UI 是託管在 GitHub Pages 上的),這點不如 LangSmith 的本地化做得好。
同類框架比較
| 維度 | Agents SDK | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|
| 形態 | SDK | 框架 + 平台 | 框架 | 框架 |
| 狀態表達 | 迴圈 + handoff | DAG 圖 | 角色協作 | 對話 |
| 上手成本 | 低 | 中 | 低 | 中 |
| Tracing | 內建 | LangSmith | 第三方 | 第三方 |
| 適合場景 | 標準化工具鏈 | 複雜工作流 | 角色扮演 | 研究 |
一句話總結:比 LangGraph 輕量,比 CrewAI 更偏 SDK 風格,比 AutoGen 更工程化。
誰適合用
適合:
- 想快速搭建生產級 Agent 工具鏈的團隊
- 已經在使用 OpenAI API 的專案
- 需要標準化 Tracing 的多 Agent 系統
- 需要 Guardrails、Handoff、Session 這些開箱即用能力的小至中型應用
不適合:
- 需要複雜 DAG / 狀態機的工作流(建議 LangGraph)
- 完全離線 / 本地部署(依賴太重)
- 國內需要穩定 Voice / Realtime 的產品
我的判斷
OpenAI 這個 SDK 不是要取代 LangGraph,而是給「已經在用 OpenAI API、想快速為 Agent 加上工程化能力」的團隊一個官方選擇。28k stars 代表社群買單。
如果你剛開始做 Agent、沒有歷史包袱,這個 SDK 的體驗是當下最順的。如果你的工作流已經是圖結構了,別為了換而換。