生成式 AI 席捲各行各業，但真正把 LLM 落地並不簡單──開發者得維運多條 API、同步提示詞、管理權限，還得處理雜亂的商業流程。複雜度一高，部署速度就被拖慢，更新也變得痛苦。OpenAI Agent SDK 應運而生：它把「智能體」「工具」「上下文」與「交接」封裝成一致介面，讓團隊專注設計動作而不是堆疊樣板程式。本文將從宏觀視角切入，再逐步深入，帶你掌握 Agent SDK 的特色、功能、應用與實作方式。
什麼是 OpenAI Agent SDK？
Agent 是具備「目標 + 工具箱」的 LLM。跟只回覆文字的聊天機器不同，Agent 能主動規劃任務、挑選工具、維持記憶並在需要時把工作交接出去。
核心概念
| 名稱 | 說明 |
|---|---|
| Agents | 具指令與記憶的智能體，負責決策與執行。 |
| Tools | Python 函式或 REST 端點，供 Agent 呼叫以讀／寫外部世界。 |
| Context | SDK 透過 RunContext 跟蹤對話、工具呼叫與回應。 |
| Handoffs | 交接機制，把對話控制權移交給另一個專科 Agent；在 LLM 眼中表現為 transfer_to_<agent> 工具。 |
SDK 優勢
- 輕量：
pip install openai-agents即用，無額外微服務。 - 靈活：任何 Python 函式都能瞬間變工具。
- 可擴展：支援 LiteLLM 與 OpenAI-Compatible 端點，輕鬆換成本地模型。openai.github.io
- 易維護：Tracing、Guardrails 與 Handoffs 把錯誤隔離在模組層。
Agent SDK 的關鍵功能
1. Function Calling：讓 LLM 自己挑函式
- 在函式上加
@function_tool裝飾器，SDK 自動產生 JSON Schema。 - LLM 依語意產出
{"name": "...", "arguments": {...}}，SDK 執行函式並回填結果。 - 應用：查匯率、訂單狀態、SQL 查詢皆可一鍵封裝。
2. Output Types：要求結構化輸出
agent = Agent(
name="JSONBot",
instructions="回傳 {title:str, summary:str}",
output_type=dict[str, str]
)
Agent 會強制 LLM 遵守格式，省去後端再解析的麻煩。
3. Streaming：邊想邊說
開啟 stream=True，SDK 以 Server-Sent Events 把 token 即時推給前端，對話無延遲。
4. Tracing：可觀測，才好維運
SDK 自帶 Tracing middleware，把每次工具呼叫、交接、模型回應寫入 span。團隊可接 Jaeger/Zipkin 追效能瓶頸。
5. Guardrails：上保險槓
以 Guardrail 檢查輸入／輸出：
from agents import Guardrail, ValidationError
no_pii = Guardrail.block_pattern(r"\d{4}-\d{4}-\d{4}-\d{4}") # 擋信用卡
agent = Agent(..., output_guardrails=[no_pii])
當 LLM 誤洩個資，SDK 直接丟 ValidationError，避免不當輸出。
入門實例
1. 環境設置
python -m venv venv && source venv/bin/activate
pip install openai-agents openai
export OPENAI_API_KEY=<your-key>
2. Hello World
from agents import Agent
greeter = Agent(
name="Greeter",
instructions="用一句台語跟使用者打招呼。"
)
print(greeter.run_sync("Say hi"))
3. 進階：本地 LLM + 外部 API
from openai import AsyncOpenAI
from agents import Agent, function_tool, set_default_openai_client
# 1️⃣ 指到本地 Ollama 端點
set_default_openai_client(AsyncOpenAI(base_url="http://localhost:11434/v1", api_key="none"))
# 2️⃣ 封裝匯率 API
@function_tool
def usd_twd() -> float:
import requests, json
return json.loads(requests.get("https://api.ratesapi.io/latest?base=USD&symbols=TWD").text)["rates"]["TWD"]
# 3️⃣ 建立 Agent
fx_bot = Agent(
name="FXBot",
instructions="回答匯率問題，必要時呼叫工具。",
tools=[usd_twd]
)
print(fx_bot.run_sync("一美元是多少台幣？"))
相關資訊
官方文件：https://openai.github.io/openai-agents-python/
Handoffs 指南：https://openai.github.io/openai-agents-python/handoffs/
LiteLLM 整合：https://openai.github.io/openai-agents-python/models/litellm/