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 介面裡可以清楚看到每個節點的輸入輸出。