OpenAI Agents SDK 教學：安裝、第一個智能體、工具與多智能體交接（Python）

本文根據 OpenAI Agents SDK 官方倉庫 README 和官方文檔 Quickstart 整理，資料核對於 2026-10-11。文中代碼取自官方頁面，沒有在本機運行驗證。還沒有 API Key 的話先看《OpenAI API Key 怎麼獲取》。

適用於誰

• 搜「openai agents sdk 教學」「openai agents sdk 使用」「openai agents sdk 是什麼」的人；
• 已經會調 OpenAI API，想從「一問一答」升級到「能自己調用工具、多步完成任務」的人；
• 在幾個智能體框架之間做選擇，想先知道官方這一套長什麼樣的人。

結論先說

1. 它是 OpenAI 官方的智能體開發框架，README 的定位是：一個輕量但功能完整的、用來構建多智能體工作流的框架。
2. 安裝一行：pip install openai-agents，需要 Python 3.10 及以上，並設定環境變量 OPENAI_API_KEY。
3. 最小程式只有三步：定義 Agent（名稱加指令）→ 用 Runner 運行 → 讀 result.final_output。
4. 兩種多智能體模式：交接（handoffs，把對話轉給另一個智能體）和把智能體當工具用（主智能體保持控制權）。
5. 自帶追蹤。每次運行的過程可以在 OpenAI 控制台的 Trace viewer 裏看到。

一、核心概念

README 列出的概念和各自的定義：

入門只需要前三個。

二、安裝與設定

bash
mkdir my_project
cd my_project
python -m venv .venv

激活虛擬環境：macOS / Linux 用 source .venv/bin/activate，Windows 用 .venv\Scripts\activate。然後安裝：

bash
pip install openai-agents

用 uv 的話是 uv init 之後 uv add openai-agents。

設定 API Key（把 sk-... 換成你自己的）：

bash
export OPENAI_API_KEY=sk-...

Windows PowerShell 的寫法是 $env:OPENAI_API_KEY = "sk-..."。

可選的附加項：語音功能 pip install 'openai-agents[voice]'，用 Redis 存會話 pip install 'openai-agents[redis]'。

三、第一個智能體

README 的 Hello world：

python
from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

• Agent(name=..., instructions=...)：instructions 相當於這個智能體的系統提示詞；
• Runner.run_sync(...)：同步運行。它內部是一個循環：調用模型，模型要用工具就執行工具，把結果交回模型，直到產出最終回答；
• result.final_output：最終的回答。

異步寫法（Quickstart 的例子）：

python
import asyncio
from agents import Agent, Runner

agent = Agent(
    name="History Tutor",
    instructions="You answer history questions clearly and concisely.",
)

async def main():
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

四、加一個函數工具

把一個普通的 Python 函數變成智能體可以調用的工具。Quickstart 當前頁面的寫法：

python
from agents import Agent
from agents.decorators import tool

@tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."

agent = Agent(
    name="History Tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)

函數的名稱、參數類型和文檔字符串會成為給模型看的工具定義。所以文檔字符串要寫清這個工具做什麼、什麼時候該用；在 instructions 裏點一下「什麼情況下用哪個工具」也有幫助。

工具的基本原理見《Claude 工具調用入門》，各家的機制是相通的。

五、多智能體：交接

一個分診智能體把問題轉給合適的專家智能體。每個專家設定 handoff_description，告訴分診者什麼時候該轉給它：

python
history_tutor_agent = Agent(
    name="History Tutor",
    handoff_description="Specialist agent for historical questions",
    instructions="You answer history questions clearly and concisely.",
)

分診者用 handoffs=[...] 聲明可以轉給誰：

python
triage_agent = Agent(
    name="Triage Agent",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor_agent, math_tutor_agent],
)

（math_tutor_agent 的定義方式和歷史老師相同。）運行時對 triage_agent 調用 Runner.run 即可。

交接和「智能體當工具」的區別：交接之後，接手的智能體直接負責後面的對話；把智能體當工具用時，主智能體始終保持控制，只是把專家的輸出當作一次工具結果。官方文檔把後者稱為 Agents as tools 模式，適合需要彙總多個專家結果的場景。

六、看運行過程

SDK 預設開啟追蹤。官方給的查看位置是 OpenAI 控制台的 Trace viewer：https://platform.openai.com/traces。在那裏可以看到每次運行裏模型調用了什麼、工具返回了什麼、在哪一步交接。

智能體行為不符合預期時，先看追蹤，再改指令或工具說明，比盲目改提示詞有效。

七、能用別家的模型嗎

README 的說法：SDK 支持 OpenAI 的 Responses API 和 Chat Completions API，並且是「provider-agnostic」的，還能通過可選依賴接入 100 多種其他大模型，README 點名的集成途徑是 any-llm 和 LiteLLM。具體配置以官方文檔為準。

Responses API 是什麼見《OpenAI Responses API》。

八、Sandbox agents

README 把它放在了顯眼的位置：預先配置好、在容器里長時間工作的智能體。README 的示例使用 UnixLocalSandboxClient，支持 macOS 和 Linux；Windows 上官方建議用 DockerSandboxClient 或託管的沙箱客戶端。細節見官方的 Sandbox agents 文檔。

常見問題

Q：和直接調 Responses API 有什麼區別？

直接調 API 時，「模型要調用工具 → 你執行 → 把結果傳回去 → 再調用」這個循環要自己寫。SDK 把循環、交接、會話歷史和追蹤都做好了。

Q：和 Claude Agent SDK 是一類東西嗎？

都是官方的智能體開發工具包，設計取向不同。Claude 那一套見《Claude Agent SDK 快速上手》。

Q：報 429 或提示額度不足？

這是 API 層面的限制，見《OpenAI API 429 錯誤》。智能體一次任務會調用模型多次，用量比單次問答大，測試時留意消耗。

Q：智能體會自己執行危險操作嗎？

它只能調用你給它的工具。有副作用的工具（刪除、付款、發消息）要麼不給，要麼配合護欄和人工確認機制使用。

參考資料

• openai/openai-agents-python（官方倉庫）：https://github.com/openai/openai-agents-python
• Quickstart（官方文檔）：https://openai.github.io/openai-agents-python/quickstart/