Agents SDK 與 Apps SDK 入門

更新時間：2026-08-12

導讀

單次 responses.create 足夠回答 FAQ；當流程變成「識別意圖 → 查庫 → 調 HTTP → 轉人工 → 輸出 JSON」時，手寫 tool 循環會很快失控。Agents SDK 把 Agent、Tool、Handoff、Guardrail 封裝成可測試的編排層，底層仍走 Responses API。Apps SDK 則面向在 ChatGPT 用戶端 內分發互動式應用。類名、套件名、支援語言以 Agents 文件 與官方 GitHub 為準——範例 import 上線前務必對照最新 repo。

核心概念速覽

Runner.run(Agent, user_input)
  → LLM：直接答 | call Tool | Handoff 到其他 Agent
  → Guardrail 攔截不合規輸入 / 輸出
  → trace 記錄每步 → final_output

概念	作用
Agent	instructions + model + tools 的設定包
Tool	函式、檢索、MCP 等可執行能力
Handoff	動態把工作階段交給專精 Agent
Guardrail	PII、越獄、格式校驗
Runner	驅動多輪推理—執行循環

SDK 是編排層，不是新模型；費用仍來自 Responses 的 token 與工具呼叫。

選型：Agents SDK 還是純 Responses？

無工具、單輪？ ──是──→ responses.create 即可
       │
       否
       ↓
固定 1–2 工具、≤3 步？ ──是──→ 手寫 tool 循環（更簡單）
       │
       否
       ↓
多 Agent 分工 / 需要 trace？ ──是──→ Agents SDK

場景	推薦
FAQ、單次摘要	純 Responses
固定查單 + 回覆	手寫 1 個 function 循環
客服分流、專精 Agent	Agents SDK + Handoff
排障、稽核每步呼叫	Agents SDK trace
ChatGPT 內公開分發	Apps SDK

原則： 先用 Responses 跑通 MVP，複雜度上升再引入 Agents SDK——避免過度設計。

Python 最小範例

import 路徑以官方 repo 為準，以下為概念程式碼：

from agents import Agent, Runner, function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """查詢訂單狀態（範例：應接真實 DB）"""
    return f"訂單 {order_id}：已出貨"

agent = Agent(
    name="OrderBot",
    instructions="你是電商助手。查單用 get_order_status，中文簡潔回答。",
    tools=[get_order_status],
    model="gpt-4o",  # 以 Models 頁當前 ID 為準
)

result = Runner.run_sync(agent, "訂單 8821 到哪了？")
print(result.final_output)

Handoff 分流

billing = Agent(name="Billing", instructions="只處理發票與退款")
general = Agent(
    name="General",
    instructions="一般問題直接答；帳單類 handoff 給 Billing",
    handoffs=[billing],
)

Handoff 讓各 Agent 的 instructions 保持短小，獨立 eval 與迭代。

Guardrails 與副作用安全

層級	範例
輸入 Guardrail	攔截 PII、越獄、超長 payload
輸出 Guardrail	JSON schema、禁止外洩 system
工具層	訂單 ID 格式、頻率限制、權限校驗

不可省略： 轉帳、刪資料、發郵件等副作用必須在伺服器端二次校驗；Guardrail 是輔助，不是唯一防線。

可觀測性與評測

• SDK trace / span：看清每步 model 與 tool，縮短排障時間
• 每個 Agent 獨立 eval 集（官方 evals 文件）
• 子任務可用 Fine-tuning 提升分類 / 格式；編排層仍用 Agents

Apps SDK：ChatGPT 生態

	Agents SDK	Apps SDK
運行處	你的伺服器	ChatGPT 用戶端 surface
目標使用者	內部 copilot、後台自動化	終端使用者、平台發現
認證	你的 API Key / OAuth	平台審核 + 連接規範
典型	客服編排、ETL	SaaS 的 ChatGPT 入口

Manifest、OAuth、審核流程見 OpenAI Apps 開發者文件；與 Platform 專案可能分開設定。

與 Assistants 的關係

Assistants（Thread / Run / Vector Store）是較早託管形態；官方引導新能力向 Responses + Agents SDK 收斂。存量見 Assistants 指南；新專案勿重複投資 Thread 模型。

參考架構

使用者 → ChatGPT App (Apps SDK) 或 你的 API
         → Agents SDK（handoff / guardrails）
           → Responses API
             → 業務 DB | [Embeddings RAG](/zh-tw/guides/openai-dev/embeddings/) | HTTP

多模態輸入見 Vision 指南。

常見問題

Agents SDK 單獨收費嗎？

SDK 開源；費用來自底層 model 與託管工具。見 定價頁。

只有 Python 嗎？

官方通常多語言；概念跨語言一致，以 repo 為準。

Handoff 和 Fine-tuning 都管路由？

Handoff 是執行時路由；微調改權重。意圖穩定時 handoff + 小模型常夠用。

國內能用 Apps SDK 嗎？

受平台政策、OAuth、網路影響；需完成 OpenAI 開發者註冊與合規要求。

Agent 無限調工具怎麼辦？

設 max_turns；每個 tool 設逾時、冪等與呼叫上限。

官方資源

• Agents 指南
• Agents SDK GitHub
• Responses API
• OpenAI Platform
• API 定價

下一步閱讀

• Responses API 繁體指南
• Assistants API 開發指南
• Embeddings（嵌入）
• OpenAI ChatGPT API 開發指南

行動路徑

今天：讀 Agents Quickstart，跑通單 Agent + 單 tool。明天：加 Handoff 第二個 Agent，用 5 條多意圖 query 測路由。本週：為危險 tool 加伺服器端校驗 + trace；若需 ChatGPT 分發再評估 Apps SDK 註冊。