框架

OpenAI Agents SDK 完整拆解:官方 Agent 框架的設計邏輯

GitHub 上 28k stars 的官方多 Agent SDK,原生支援 100+ LLM,內建 Tracing、Guardrails、Sessions。本文從程式碼、架構、橫向比較切入,評估它是否值得花一個下午上手。

字級

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 SDKLangGraphCrewAIAutoGen
形態SDK框架 + 平台框架框架
狀態表達迴圈 + handoffDAG 圖角色協作對話
上手成本低中低中
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 的體驗是當下最順的。如果你的工作流已經是圖結構了,別為了換而換。

來源: https://github.com/openai/openai-agents-python