OpenAI Agents SDK：把 AI Agent 的「最佳實踐」直接做進框架裡

如果說其他 AI Agent 框架是「工具箱」，那 OpenAI Agents SDK 是「已經裝好標準配備的工廠套件」。

2025 年初，OpenAI 在靜悄悄完成一輪內部驗證後，正式發布了 OpenAI Agents SDK——這不是一個新概念，而是他們把過去兩年從 Swarm 實驗到 GPT-4o 上線學到的所有教訓，直接烘焙進框架裡的結晶。

它的核心主張只有一句話：你不需要自己造輪子，Agent 需要的基礎建設，我們幫你內建好了。

這聽起來像是在替使用者著想，但也可以解讀為：OpenAI 希望讓整個 Agent 生態系標準化，而它自己來定義那個標準。

• 從 Swarm 到 Agents SDK：一段「實驗 → 生產」的演進
• Agents SDK 的四大核心設計
  • 1. Agent：有名字、有指令、有工具的角色
  • 2. Runner：負責跑完整個 Agent Loop
  • 3. Handoff：Agent 之間的控制權交接
  • 4. Guardrails：輸入輸出的防護欄
• Tracing：把 Agent 的每一步都記錄下來
• Agents SDK vs 其他框架：選誰的關鍵問題
• 經典語錄
• 實用建議：三個起步行動
  • 步驟 1：用最簡單的一個 Agent + 一個工具開始
  • 步驟 2：開啟 Tracing，從第一個請求就開始觀察
  • 步驟 3：用 Guardrails 而不是在 Prompt 裡寫禁止清單
• 我的反思
• 參考資料 (References)

從 Swarm 到 Agents SDK：一段「實驗 → 生產」的演進

要理解 Agents SDK，必須先認識它的前身——Swarm。

2024 年 10 月，OpenAI 悄悄在 GitHub 發布了 Swarm。它的 README 第一行就寫著：

"Swarm is currently an experimental sample framework intended to explore ergonomic interfaces for multi-agent systems. It is not intended to be used in production."

這是一個刻意低調的姿態。OpenAI 想測試一件事：「Handoff（交接控制權）」這個概念，是不是 Multi-Agent 系統最簡潔的設計核心？

Swarm 的架構極其精簡——Agent、函數工具、Handoff，僅此而已。開發者社群的反應出乎意料地熱烈。

幾個月後，OpenAI 把這次實驗的結論升格成正式產品，加入了 Swarm 缺少的生產環境必要元件：

這張表格本身就說明了一切：Swarm 是問卷，Agents SDK 是答案。

Agents SDK 的四大核心設計

1. Agent：有名字、有指令、有工具的角色

from agents import Agent, function_tool

@function_tool
def search_web(query: str) -> str:
    """搜尋網路上的即時資訊"""
    # 實際呼叫搜尋 API
    return f"搜尋結果：{query} 相關的最新資訊..."

agent = Agent(
    name="研究助理",
    instructions="""
    你是一位專業的市場研究助理。
    - 遇到需要即時資料的問題，使用 search_web 工具
    - 回答需要有數據支撐，並標明資料來源
    - 最終輸出以條列式整理
    """,
    tools=[search_web],
    model="gpt-4o",  # 可替換為其他支援的模型
)

Agent 的設計刻意接近自然語言：instructions 就是給 AI 的角色說明，tools 是它能用的工具。這比 LangGraph 的 Node 定義更直覺，也比 CrewAI 的 role/goal/backstory 三欄式更簡潔。

2. Runner：負責跑完整個 Agent Loop

import asyncio
from agents import Runner

async def main():
    result = await Runner.run(
        agent,
        "分析台灣半導體產業的未來三年機會與風險"
    )
    print(result.final_output)

asyncio.run(main())

Runner 把「Agent Loop」這件事完全封裝起來，內部自動處理：

1. 把訊息送給 LLM
2. 如果 LLM 想呼叫工具 → 執行工具 → 把結果塞回去
3. 如果 LLM 想 Handoff 給另一個 Agent → 切換 Agent 繼續
4. 直到 LLM 給出最終回答 → 回傳 result.final_output

你有三種執行方式：

3. Handoff：Agent 之間的控制權交接

這是 Agents SDK 最具設計感的特性，也是從 Swarm 繼承並改良的核心概念。

from agents import Agent, handoff, Runner

# 定義三個專業 Agent
billing_agent = Agent(
    name="帳務專員",
    instructions="處理付款、退款、發票相關問題",
)

tech_agent = Agent(
    name="技術支援",
    instructions="處理產品使用、Bug 回報、帳號設定等技術問題",
)

# 前台接待 Agent：根據問題類型，交接給對應的專業 Agent
triage_agent = Agent(
    name="前台客服",
    instructions="""
    你是客服前台，負責判斷用戶需求：
    - 帳務、付款、退款問題 → 轉給帳務專員
    - 技術、使用、Bug 問題 → 轉給技術支援
    """,
    handoffs=[
        handoff(billing_agent),
        handoff(tech_agent),
    ],
)

result = Runner.run_sync(triage_agent, "我的上個月帳單多扣了一筆費用")
print(result.final_output)
# → 帳務專員接手並回答

Handoff 的精妙之處在於：它不是硬編碼的路由規則，而是讓 LLM 根據對話內容動態決定「現在該交給誰」。這讓系統在保持結構清晰的同時，具備真正的彈性。

4. Guardrails：輸入輸出的防護欄

這是 Agents SDK 相比所有開源框架最大的差異化功能——把安全檢查做成框架的一等公民。

from agents import Agent, Runner, GuardrailFunctionOutput, input_guardrail
from pydantic import BaseModel

class ContentCheck(BaseModel):
    is_safe: bool
    reason: str

@input_guardrail
async def check_sensitive_content(ctx, agent, input) -> GuardrailFunctionOutput:
    """防止用戶輸入敏感或不當內容"""
    # 可以呼叫另一個 LLM 或規則引擎進行檢查
    if "競爭對手" in str(input):
        return GuardrailFunctionOutput(
            output_info=ContentCheck(is_safe=False, reason="不討論競爭對手"),
            tripwire_triggered=True,  # 觸發防護欄，中止執行
        )
    return GuardrailFunctionOutput(
        output_info=ContentCheck(is_safe=True, reason="內容安全"),
        tripwire_triggered=False,
    )

safe_agent = Agent(
    name="企業助理",
    instructions="回答公司產品相關問題",
    input_guardrails=[check_sensitive_content],
)

Guardrail 可以掛在輸入前（input_guardrail）或輸出後（output_guardrail），讓你在不修改核心 Agent 邏輯的情況下，疊加各種安全政策。

Tracing：把 Agent 的每一步都記錄下來

Agents SDK 預設開啟 Tracing，每一次 LLM 呼叫、工具執行、Handoff 切換，都會自動記錄到 OpenAI 的 Traces Dashboard。

# 不需要任何額外設定，只要有 OPENAI_API_KEY，Tracing 就自動啟用
import os
os.environ["OPENAI_API_KEY"] = "sk-..."

# 所有的 Runner.run() 呼叫都會被追蹤
result = await Runner.run(agent, "幫我分析這份財報")
# → 自動記錄：輸入、LLM 推理、工具呼叫、輸出、延遲、Token 消耗

這個設計對應了 LangSmith 在 LangChain 生態系扮演的角色——但 Agents SDK 把它做成預設行為，而不是需要另外訂閱的附加服務。

Agents SDK vs 其他框架：選誰的關鍵問題

OpenAI Agents SDK 最大的優勢，也是它最大的侷限：它跟 OpenAI 的生態系深度綁定。Tracing 進 OpenAI Dashboard、模型預設用 GPT-4o、最佳化也是圍繞 OpenAI 的工具呼叫格式設計。

如果你接受這個「鎖定」，你能換來極低的工程複雜度；如果你不接受，LangGraph 是更中立的選擇。

經典語錄

"Agents are the future of AI applications. The question is not whether to use agents, but how to build them reliably."

Agent 是 AI 應用的未來。問題不是要不要用 Agent，而是怎麼把它做得可靠。

"Swarm was a question. Agents SDK is our answer."

Swarm 是一個問題，Agents SDK 是我們的答案。

實用建議：三個起步行動

步驟 1：用最簡單的一個 Agent + 一個工具開始

pip install openai-agents
export OPENAI_API_KEY=sk-...

不要一開始就設計多 Agent 系統。先讓一個 Agent 學會用一個 @function_tool，感受「LLM 判斷何時呼叫工具」的過程。這個感覺建立起來之後，加入更多工具和 Handoff 就會很自然。

步驟 2：開啟 Tracing，從第一個請求就開始觀察

直接上 platform.openai.com/traces 看你的 Agent 在做什麼。能「看見」Agent 的推理過程，比死背文件更有效——你會在 Dashboard 上清楚看到它何時決定呼叫工具、為什麼做 Handoff、哪個步驟消耗了最多 Token。

步驟 3：用 Guardrails 而不是在 Prompt 裡寫禁止清單

很多開發者習慣在 instructions 裡寫「不要回答 X、不要討論 Y」，但這在生產環境裡不可靠。把這些規則移到 input_guardrail 或 output_guardrail——它們是獨立的檢查層，不受 Prompt Injection 攻擊影響。

我的反思

看完整個 AI Agent 系列的演進，有一件事越來越清晰：

每個框架解決的，都是同一個問題的不同切面。

• LangChain 解決「怎麼接」
• CrewAI 解決「怎麼分工」
• LangGraph 解決「怎麼控制流程」
• AutoGen 解決「怎麼讓 AI 互相對話」
• OpenClaw 解決「在哪裡互動」
• Agents SDK 解決「怎麼讓這一切在生產環境安全地跑起來」

OpenAI 做 Agents SDK 的姿態，和它推出 ChatGPT 時非常像——不是第一個做這件事的，但它把「讓一般開發者也能用」這件事做得最徹底。

代價是：你在換取易用性的同時，也在讓自己更依賴 OpenAI 的生態系。這沒有對錯，只是一個選擇——而且是一個值得在設計系統初期就想清楚的選擇。

參考資料 (References)

官方資源

• OpenAI Agents SDK GitHub
• OpenAI Agents SDK 官方文件
• OpenAI Swarm（前身）GitHub

推薦影片