OpenAI Agents SDK（Python）：三個概念就夠，從零到多 Agent 系統的最快路徑
OpenAI 在 2025 年 3 月推出的 Agents SDK，用 Agent、Handoff、Guardrail 三個 primitive 建構多 Agent 系統，20.3K stars、4,800+ 個專案在用。這篇拆解三個核心概念，再跟 LangGraph 和 Claude Agent SDK 做清楚比較。
目錄+
2025 年 3 月，OpenAI 正式推出 Agents SDK，宣告取代前一個實驗性框架 Swarm。Swarm 的問題是明確的：它是 demo 等級的工具，幾乎沒有生產所需的 tracing、guardrail、或狀態管理。Agents SDK 這次不一樣——20.3K GitHub stars、4,800 以上的下游依賴、236 位貢獻者，這個數字代表的是真實的使用量，不是 hype。
截至 2026 年 4 月，最新版本是 v0.14.2。同月中的一次重大更新加入了 sandbox agents、可配置記憶體、類 Codex 的 filesystem tools，以及 MCP 整合。如果你是 Python developer 或 indie builder，想快速讓多個 agent 協作完成任務，這篇文章幫你把三個核心概念說清楚，再告訴你什麼情境下不該選它。
三個核心概念
Agent：封裝 LLM 行為的基本單元
Agent 是 OpenAI Agents SDK 的第一個 primitive。它把一個 LLM 呼叫連同它的 instructions、tools、guardrails、handoffs 封裝成一個可組合的單元。
from agents import Agent, Runner
agent = Agent(
name="assistant",
instructions="你是一個客服助理，只處理帳單相關問題。",
tools=[lookup_invoice, create_refund],
)
result = Runner.run_sync(agent, "我的上個月帳單是多少？")
print(result.final_output)
instructions 決定 agent 的角色定位，tools 是它可以呼叫的函式（Python function 加上型別標註就能自動轉成 tool schema）。一個 Agent 物件可以被多個 runner 共用，本身是 stateless 的設計。
Handoff：把完整控制權交出去
Handoff 是 OpenAI Agents SDK 最關鍵的設計決策，也是它跟一般「呼叫另一個 LLM」最本質的差別。
當 agent A 執行一個 tool call，工具執行完畢後控制權回到 A，A 繼續決定下一步。但當 agent A 執行一個 handoff，控制權從此刻起移交給 agent B——A 退出執行迴圈，B 接管後續所有決策。
這個語義差別在多 agent 系統裡非常重要。一個典型的 fan-out 模式是 triage agent 判斷使用者意圖後，把請求路由給對應的 specialist agent：
Triage Agent 的工作只有一件事：分類並移交。Billing Agent 接手之後，它有自己的 instructions 和 tools，整個對話上下文（conversation history）會一起傳遞過去，不需要重新初始化。
billing_agent = Agent(name="billing", instructions="處理帳單查詢。")
refund_agent = Agent(name="refund", instructions="處理退款申請。")
triage_agent = Agent(
name="triage",
instructions="根據使用者需求，handoff 到對應的 agent。",
handoffs=[billing_agent, refund_agent],
)
Guardrail：兩層驗證，一個斷路器
Guardrail 是輸入和輸出的驗證層。它可以是一個 Python function，也可以是另一個 LLM agent（用來做語意層面的判斷）。
關鍵機制是 tripwire：guardrail 一旦觸發失敗條件，整個執行鏈立刻中止，不會繼續呼叫 LLM 或執行後續 tool。這對需要過濾有害輸入、防止資料洩露的場景特別實用。
Input guardrail 在 agent 收到使用者輸入後立刻執行；output guardrail 在 agent 產出回覆後、傳給使用者前執行。兩層可以獨立配置，也可以同時掛上多個 guardrail。
Runner 執行模型
SDK 提供三種執行模式，對應不同的使用情境：
Runner.run_sync()：同步阻塞執行，最簡單。適合 script、CLI 工具、或不需要非同步架構的快速原型。整個 agent loop 跑完才返回，回傳 RunResult。
Runner.run()：async 版本，適合在 FastAPI、async web framework 或需要同時跑多個 agent 的情境。回傳同樣的 RunResult，但不阻塞 event loop。
Streaming event loop：逐步接收 agent 的中間事件（tool call、token streaming、handoff 發生），適合需要即時反饋的 UI 場景，例如把 agent 思考過程串流給前端。
# 同步（script / CLI）
result = Runner.run_sync(agent, input)
# 非同步（FastAPI / async 應用）
result = await Runner.run(agent, input)
# Streaming（需要即時事件的 UI）
async for event in Runner.run_streamed(agent, input):
print(event)
框架對比
| 維度 | OpenAI Agents SDK | LangGraph | Claude Agent SDK |
|---|---|---|---|
| 語言 | Python（TypeScript 分開維護） | Python | Python + TypeScript |
| 多 Agent 協作 | Handoff（委派模式） | Graph node（狀態機） | Sub-agents |
| LLM 支援 | OpenAI 優先，100+ via LiteLLM | 任意（model-agnostic） | Claude 優先（支援 Bedrock/Vertex） |
| 狀態持久化 | Sessions（輕量） | Checkpointing（強） | CLAUDE.md 記憶機制 |
| 內建可觀測性 | Tracing UI | LangSmith | 無（需外掛） |
| 學習曲線 | 低（幾小時可跑） | 高（1-2 週） | 低（概念直觀） |
| 最適合 | GPT 生態快速 prototype | 複雜有狀態工作流 | Safety 優先 / MCP 原生 |
選 OpenAI Agents SDK：你的主力模型是 GPT 系列、需要快速上線、agent 數量在 5-8 個以內，且不需要複雜的狀態恢復機制。內建 Tracing UI 讓你不需要額外配置就能 debug 多 agent 執行過程。
選 LangGraph：你的工作流有明確的狀態轉移邏輯、需要可靠的 checkpointing（中途失敗可以從上次的 checkpoint 繼續）、或你的團隊已經在用 LangChain 生態。LangGraph Platform 被 Cisco、Uber、LinkedIn 使用，每月 PyPI 下載量達 3800 萬，是目前最成熟的有狀態 agent 框架。
選 Claude Agent SDK：你的首要考量是安全性與可稽核性、需要 MCP 原生整合、或你的應用場景對 Claude 的 safety 特性有依賴。Python 和 TypeScript 同步維護，適合全端 builder。
批判視角
Agents SDK 的 handoff pattern 在 agent 數量少的時候很清晰，但當系統擴展到 8-10 個以上的 agent 類型時，triage logic 會急速複雜化——你需要在 instructions 裡描述愈來愈多的路由條件，維護成本不亞於直接寫 graph 結構。
Sessions 提供輕量的對話持久化，但它不是 LangGraph checkpointing 的替代品。如果你的 agent 工作流需要從中間節點恢復（例如一個跑了 30 分鐘的任務在第 20 分鐘失敗），Sessions 目前沒有辦法做到這件事。
2026-04-15 的更新雖然補上了 sandbox agents 和 filesystem tools，補齊了生產部署的重要缺口，但 TypeScript 版本目前仍落後 Python 版本的功能迭代速度。如果你的專案是 TypeScript-first，需要留意功能可用性的時間差。