OpenAI Agents SDK 完整教學：用 Python 打造多 Agent 應用程式（2026）
去年底 OpenAI 正式推出 Agents SDK，讓我研究了好幾個週末。說實話，第一次看到它跑起來的時候真的有點驚艷——以前要自己拼裝一堆工具才能實現的多 Agent 協作，現在用幾十行 Python 就搞定了。這篇文章就來分享我的實戰心得，從環境建置到多 Agent 架構，一步一步帶你上手。
什麼是 OpenAI Agents SDK？
OpenAI Agents SDK 是 OpenAI 在 2025 年底正式發布的開源框架，前身是實驗性的 Swarm。它的核心理念很簡單：讓多個 AI Agent 能夠互相協調、傳遞任務，每個 Agent 都有自己的角色定義、工具清單，以及明確的「移交」規則。
跟其他框架比較起來，OpenAI Agents SDK 有幾個特點讓我很喜歡：輕量、原生支援 OpenAI 的 function calling、內建 handoff 機制，而且 tracing 功能做得很完整，debug 起來不會一頭霧水。如果你之前用過 LangChain Agent，會發現 Agents SDK 的 API 設計更加直覺。
環境安裝與基礎設定
先來把環境搞定。建議用 Python 3.11 以上版本，搭配虛擬環境管理：
python -m venv agents-env
source agents-env/bin/activate
pip install openai-agents然後設定 API Key，建議放在 .env 檔案裡，程式碼裡用 dotenv 載入。SDK 會自動讀取 OPENAI_API_KEY 環境變數。
建立第一個 Agent
來寫個最簡單的範例：
from agents import Agent, Runner
customer_service_agent = Agent(
name="客服小幫手",
instructions="你是一位專業的客服人員，回答使用者關於產品的問題，語氣親切有禮。",
model="gpt-4o"
)
result = Runner.run_sync(customer_service_agent, "請問你們的退換貨政策是什麼？")
print(result.final_output)Runner.run_sync 是同步執行，適合腳本場景；非同步框架可改用 await Runner.run()。
為 Agent 加入工具（Tools）
真實應用裡 Agent 需要能執行動作。這裡用到 Tool 定義，本質上就是 LLM Function Calling 的封裝：
from agents import Agent, Runner, function_tool
@function_tool
def search_order(order_id: str) -> str:
"""根據訂單編號查詢訂單狀態。"""
mock_data = {"ORD-12345": "已出貨，預計 2 個工作天送達"}
return mock_data.get(order_id, f"找不到訂單 {order_id}")
agent = Agent(
name="進階客服",
instructions="你是客服，可以查詢訂單狀態，主動使用工具幫助用戶。",
tools=[search_order],
model="gpt-4o"
)
result = Runner.run_sync(agent, "我的訂單 ORD-12345 到哪裡了？")
print(result.final_output)@function_tool 裝飾器會自動把 Python 函式的 docstring 和 type hints 轉換成 JSON Schema。
多 Agent 架構：Handoff 機制
這才是 Agents SDK 最有趣的部分。Handoff（移交）讓一個 Agent 可以把對話移交給另一個更專業的 Agent：
from agents import Agent, Runner
tech_support = Agent(name="技術支援", instructions="處理技術問題", model="gpt-4o")
refund_agent = Agent(name="退換貨專員", instructions="處理退換貨", model="gpt-4o")
front_desk = Agent(
name="前台客服",
instructions="判斷需求並轉介：技術問題轉技術支援，退換貨轉退換貨專員",
handoffs=[tech_support, refund_agent],
model="gpt-4o"
)
result = Runner.run_sync(front_desk, "藍牙耳機右耳沒聲音，想換貨")
print(result.final_output)整個過程在 tracing 介面裡可以清楚看到每個節點的輸入輸出。
輸入輸出守衛（Guardrails）
生產環境裡不能讓 Agent 亂說話，Guardrails 是 SDK 內建的防護機制，可以在輸入或輸出階段攔截不安全的內容。
非同步串流與實戰建議
整合進 Web 應用時，非同步串流是必備的。實際開發多 Agent 系統的踩坑心得：Instructions 要精準、善用 tracing、控制 token 消耗、工具函式要有完善的錯誤處理。
與其他框架的選擇建議
OpenAI Agents SDK 最適合已經深度使用 OpenAI API 的團隊；需要更複雜的 DAG 工作流可考慮 LangGraph；角色扮演式協作可看看 AI Agent Framework 的完整比較。
結語
OpenAI Agents SDK 把多 Agent 協作的門檻降低了很多。先用小範例把核心概念跑通，再慢慢擴充到真實業務場景。Agent 應用開發最難的其實不是技術，而是把業務流程想清楚。