自建 Agent SDK 與自訂代理人

12.1　它是什麼、什麼時候用

前面每一章，都是「你親自打字、跟 Claude Code 對話」。這一章換個角度：Agent SDK 讓你用程式碼，打造一個「你自己的 AI 代理人」——換句話說，不是你坐在終端機前下指令，而是你寫一段程式，讓它在背後自動跑、自動完成你交代的任務。

最棒的是，你不用從零造輪子。Agent SDK 內建了跟 Claude Code 一模一樣的那套工具（讀檔、改檔、搜尋、跑指令）、同一套 agent loop（代理迴圈），以及上下文管理。你只要描述「我要它做什麼」，剩下的它自己張羅。

那這東西實際能做什麼？打個比方：你可以把它想成「請一位只負責一件事、但 24 小時待命的數位員工」。常見的例子有——線上系統出狀況時自動診斷、嘗試修復的 SRE 代理人；幫團隊跑程式碼審查、強制大家照同一套風格的審查代理人；值班時自動把事件分類、分流給對的人的助手；甚至是幫忙初步審閱合約的法務助理。它們的共同點是：規則清楚、可以一直重複做，很適合交給代理人。

剛剛那個「想知道原理」的方塊，講的是 Client SDK 跟 Agent SDK 的差別——誰來寫那段工具呼叫迴圈。把視野再拉大一點，外面其實還有第三層，三層放在一起看，你會更清楚 Agent SDK 站在哪個位置：

本章接下來全部圍繞第二層。第三層目前還在早期階段，實際能力與計費方式請以官方文件為準，這裡先讓你知道「有這個更省心的選項存在」就好。

12.2　怎麼開始：選語言、裝起來、跑第一個範例

講完概念，來動手。Agent SDK 支援兩種程式語言，你挑你熟的那種就好——下面先用一張表幫你對照，再帶你裝起來、跑出第一個會自己動手的小代理人。

先把 SDK 裝起來

依你上面選的語言，挑對應那一行裝起來就好。兩種各跑一行指令，不用兩個都裝。

💡 建議執行：依你選的語言，把 SDK 裝起來

# TypeScript：用 npm 安裝 Agent SDK
npm install @anthropic-ai/claude-agent-sdk

# Python：用 pip 安裝（需 Python 3.10 以上）
pip install claude-agent-sdk

# Mac／Linux：確認 Python 版本
python3 --version

# Windows：確認 Python 版本
py --version

跑出第一個會自己動手的代理人

下面帶你跑出第一個代理人：它會去讀你資料夾、用 Glob 工具把檔案列出來，再告訴你結果——全程它自己決定要用哪個工具，你只是按下執行。我們用 TypeScript 示範（這是本書唯一一段「真的程式碼」，看不懂沒關係，照著貼、跑起來、看它動，就達標了）。

1. 1
   ✋動手做

   確認你裝好了 Node.js 和 Agent SDK

   這個範例用 TypeScript 跑，需要你的電腦有 Node.js，而且已經照上面 12.2 裝好 @anthropic-ai/claude-agent-sdk。沒裝 Node.js 的話，先到 nodejs.org 裝好再回來。

2. 2
   ✋動手做

   新建一個檔案叫 agent.ts，貼進下面這段

   在你想試的資料夾裡，建立一個檔名為 agent.ts 的檔案，把下面整段程式碼貼進去存檔。看不懂每一行沒關係——重點是它在說「請列出這個資料夾的檔案，只准用 Glob 和 Read 這兩個工具」。

   import { query } from "@anthropic-ai/claude-agent-sdk";
   
   for await (const message of query({
     prompt: "這個資料夾裡有哪些檔案?",
     options: { model: "opus", allowedTools: ["Glob", "Read"], maxTurns: 250 }
   })) {
     if (message.type === "assistant") {
       for (const block of message.message.content) {
         if ("text" in block) console.log(block.text);
       }
     }
   }

   複製
3. 3
   ✋動手做

   在終端機執行它

   回到終端機，在 agent.ts 所在的資料夾，打下面這行按 Enter。npx tsx 會幫你把這段 TypeScript 直接跑起來，不用先編譯。

   npx tsx agent.ts

   複製

   ✅ 預期會看到

   # 它會先用 Glob 工具掃一遍資料夾，然後用文字回覆你
   # 大致會印出像這樣的內容（實際清單依你的資料夾而定）：
   這個資料夾裡有這些檔案：agent.ts、package.json、README.md …

   複製

跑起來之後你會發現：你從頭到尾沒教它「怎麼列檔案」，是它自己決定去用 Glob 工具的。這就是 Agent SDK 的價值——你可以精細控制它能用哪些工具（allowedTools）、最多跑幾輪（maxTurns），還能用「系統提示」定義這個代理人的角色和行為。給它的權限越小，它越安全、越可控。

認證：SDK 怎麼知道你是誰

剛剛那個範例能跑起來，是因為你的電腦已經在前面章節登入過 Claude Code，Agent SDK 直接沿用了那個登入狀態。但如果你要把代理人搬到別的地方跑——例如一台 CI 伺服器、雲端主機，或任何沒有互動登入過的環境——就得改用API 金鑰：設定環境變數 ANTHROPIC_API_KEY，SDK 會自動去讀。

如果你的組織是走第三方雲端平台接 Claude（不是直接用 Anthropic 的 API），SDK 也支援，各自開一個環境變數就好：

這幾個平台的名字、設定細節都可能隨時間調整，正式串接前務必回官方文件核對最新版本，這裡只是先讓你知道「有這條路可走」。

12.3　給代理人配工具：內建工具與自訂工具

代理人能做事，靠的就是「工具」。上一節你已經看過 allowedTools 怎麼限定它能用哪些——這一節退回來一步，帶你認識工具本身：SDK 內建了哪些現成工具，以及怎麼自己寫一個工具，讓代理人做內建工具做不到的事。

內建工具：跟你平常用的 Claude Code 是同一套實作

Agent SDK 內建的工具，跟你直接在終端機打字用 Claude Code 時看到的是同一套實作，不是另外簡化過的版本：

也因為底層共用，第 9 章你學過的 MCP 外部工具連線（接資料庫、Slack 之類），一樣能透過 mcpServers 這個選項掛進 Agent SDK 的代理人，設定方式跟你在 .mcp.json 裡寫的大同小異。

自訂工具：讓代理人做內建工具做不到的事

內建工具之外，你也可以自己寫一個工具，接你自己的 API、資料庫，或任何內部系統。定義一個自訂工具要交代四件事：名字、給 Claude 看的說明、輸入參數長什麼樣（input schema）、以及真正執行的那段程式（handler）。Python 寫法最精簡——用一個 dict 把參數名對到型別就好，SDK 會自動轉成 Claude 看得懂的格式；真的需要列舉值、數字範圍、巢狀物件這種複雜結構時，也能直接塞一份完整的 JSON Schema 進去。

定義好之後還有一步別漏掉：用 create_sdk_mcp_server（TypeScript 是 createSdkMcpServer）把一個或多個工具包成一台迷你 MCP 伺服器——這台伺服器跑在你自己的程式行程裡，不是另外開一個子行程，啟動快，也不必額外管理生命週期。包好之後透過 query() 的 mcpServers 選項掛上去就能用：

# 一個查天氣的自訂工具，示範四要素：名字、說明、輸入 schema、handler
from typing import Any
import httpx
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("get_weather", "查詢指定城市目前的天氣", {"city": str})
async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.example.com/weather", params={"city": args["city"]}
        )
        data = resp.json()
    return {
        "content": [{"type": "text", "text": f"{args['city']} 目前 {data['temp']}°C"}]
    }

# 包成一台跑在你程式裡的迷你 MCP 伺服器
weather_server = create_sdk_mcp_server(name="weather", version="1.0.0", tools=[get_weather])

options = ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

工具出錯了怎麼辦：isError 的用法

如果你的 handler 執行到一半噴出未捕捉的例外，SDK 不會讓整個 agent loop 中斷——它會自動把這次呼叫轉成一個錯誤結果，將原始錯誤訊息丟給 Claude 自己判斷怎麼辦。這個自動接住的行為很方便，但訊息通常是程式語言原生的錯誤字串，Claude 不一定看得懂上下文。想給更有用的說明，可以自己接住錯誤、回傳 is_error: True（TypeScript 是 isError: true），夾帶你自己組的訊息：

# 自己接住錯誤，給 Claude 一句看得懂上下文的說明
return {
    "content": [{"type": "text", "text": f"查詢失敗：氣象站回應 {resp.status_code}，可能是城市名稱打錯"}],
    "is_error": True,
}

記住一個容易搞混的地方：isError 只決定「Claude 讀到的是什麼訊息」，跟這次 query() 呼叫本身有沒有失敗是兩件事——就算工具回了錯誤，整個代理人流程還是會繼續跑，Claude 通常會嘗試換個方式，或照實跟你回報做不到。

12.4　權限護欄：從 allowedTools 到六步驟判定順序

代理人會自己動手改檔、跑指令，「它能做什麼」這件事的控制權，比前面幾章互動式操作時更重要——沒有人在旁邊隨時盯著它、隨時喊停。這一節把 Agent SDK 的權限系統攤開講清楚，尤其是一個很多人會誤踩、而且錯了不容易發現的地方。

先分清楚：「看不看得到」跟「能不能用」是兩回事

tools 決定的是看不看得到——這個工具存不存在於 Claude 的 context 裡。allowedTools 決定的是能不能用——工具就算看得到，呼叫前要不要先問過你。這兩層很容易被當成同一件事，但行為差很多：disallowedTools 如果寫的是工具的裸名字（像 "Bash"），效果是把整個工具從 context 移除，Claude 根本不會嘗試去用；但如果寫的是帶條件的規則（像 "Bash(rm *)"），工具本身還在，只是符合條件的那次呼叫會被擋下來。

六步驟判定順序：一次工具呼叫怎麼被放行或擋下

每一次代理人想用工具，SDK 都照固定的六個步驟依序判斷，前面的步驟一旦有結論，後面就不會再看：

1. Hooks——PreToolUse 這類生命週期 hook 最先跑，它可以直接擋下呼叫，就算後面每一步都會放行也沒用。
2. Deny 規則——disallowedTools 或 settings.json 裡的 deny 清單，命中就直接擋，連下面第 4 步的 bypassPermissions 都擋不掉它。
3. Ask 規則——settings.json 裡明確寫「這個要問」的規則，命中會落到第 6 步的 canUseTool；但如果權限模式是 dontAsk，就直接改判拒絕，不會真的跑去問。
4. Permission mode——依你設定的模式判斷（下面表格細講），例如 bypassPermissions 到這步幾乎全部放行、acceptEdits 會放行檔案編輯。
5. Allow 規則——allowedTools 或 settings.json 裡的 allow 清單，命中直接核准。
6. canUseTool callback——前面五步都沒給出結論，才輪到你自己寫的這個函式做最後判斷。

canUseTool：真的被呼叫到時，它能做什麼

走到第 6 步時，canUseTool 是你能檢視 Claude 提出的確切參數、做最後判斷的地方——可以直接拒絕，也可以核准前先動手改寫參數再放行：

// 示意：擋下危險的 rm -rf，其餘照常放行
async function canUseTool(toolName, input) {
  if (toolName === "Bash" && /rm\s+-rf/.test(input.command)) {
    return { behavior: "deny", message: "不准跑 rm -rf，太危險了" };
  }
  return { behavior: "allow", updatedInput: input };
}

實際的型別名稱、寫法細節請以官方 SDK 文件為準（版本變動快），這裡只示意判斷邏輯長什麼樣。生產環境更常見的做法，其實是把上一段的坑反過來用：allowedTools 列清楚該給的工具，搭配 permissionMode: "dontAsk"——列出的自動核准，沒列出的一律直接拒絕，而不是賭一個可能忘記寫、或根本不會被呼叫到的 callback。

permissionMode 六種模式一覽

12.5　讓子代理人變成程式的一部分

第 10 章你已經在對話裡用 /agents 建過子代理人，第 16 章又講了怎麼編排一群子代理人。Agent SDK 讓你用兩種方式做同一件事：直接寫在程式碼裡，或繼續沿用 .claude/agents/ 底下的檔案。這一節帶你看這兩條路怎麼接、以及只有寫程式才會摸到的細節欄位。

直接在程式碼裡定義：AgentDefinition

用 agents 這個選項，直接把子代理人的定義寫進 query() 裡，不必另外開檔案。每個定義要給 description（Claude 依它判斷什麼時候該委派）、prompt（相當於檔案版子代理人開頭那段系統提示）、tools，也可以指定 model。要讓 Claude 真的能呼叫某個子代理人，記得把 Agent 這個工具本身加進主 query() 的 allowedTools——子代理人是透過呼叫 Agent 這個工具被叫出來的：

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="專門做程式碼品質與安全審查的審查員",
            prompt="檢查程式碼品質與潛在的安全問題，給出具體改善建議。",
            tools=["Read", "Glob", "Grep"],
        )
    },
)

子代理人跑起來後，它送回的每則訊息會帶一個 parent_tool_use_id 欄位，標明這則訊息屬於哪個子代理人——自己刻監看畫面、想分開顯示不同子代理人的輸出時用得到。

沿用 .claude/agents/ 檔案：SDK 跟互動模式認同一套格式

好消息是你不用為了 SDK 重寫一份子代理人定義。SDK 預設會讀你專案裡 .claude/skills/、.claude/commands/、.claude/agents/、CLAUDE.md 這些檔案系統設定——跟你平常互動操作 Claude Code 時是同一批檔案。想限制它只讀特定來源，用 setting_sources（TypeScript 是 settingSources）調整。子代理人檔案的 frontmatter 除了第 16 章講過的 tools，還有幾個只有深入用才會碰到、但很好用的欄位：

另外還有 background（強制它一律背景執行）、effort（覆蓋這個子代理人的推理力氣，第 8 章講過這個概念）、color（面板顯示用的顏色）、initialPrompt（這個定義被當成主 session 執行時自動送出的第一句話）幾個比較少用到的欄位，知道有就好，用到的時候再回頭查。

存放位置與優先序：同名子代理人，SDK 選哪一個

子代理人檔案能放在好幾個地方，同名時 SDK 依下面順序、由高到低取用最先命中的那個：

1. Managed settings（組織層級統一部署）
2. --agents 這個 CLI 參數（只在那次執行有效，不會存檔，適合臨時測試）
3. .claude/agents/（專案層級，會沿著工作目錄往上層逐層找到 repo 最頂端；建議進版控跟團隊共享）
4. ~/.claude/agents/（使用者層級，你自己所有專案共用）
5. Plugin 裡的 agents/ 資料夾（隨外掛啟用範圍生效，優先序最低）

專案與使用者層級都能整理成子資料夾（像 agents/review/），子資料夾路徑不影響識別，Claude 只認 name 欄位；但如果是外掛提供的子代理人，子資料夾就會變成識別字串的一部分，例如 agents/review/security.md 在 my-plugin 這個外掛裡會註冊成 my-plugin:review:security。

內建的三個系統子代理人

不用你自己定義，SDK 內建就有三個現成的子代理人可以直接委派：

巢狀 spawn、前景背景、還有一個便宜的分身：/fork

12.6　動手前先知道的坑：常見錯誤與排除法

下面整理幾個「文件沒明講、真的寫下去才會撞到」的狀況，多半是社群和個別開發者實測回報的經驗，不是官方規格保證的行為——遇到時當作排除方向的起點，實際訊息以你當下版本印出來的為準。

12.7　小結

這一章是全書最深的地方，範圍也拉得比其他章寬：從 query() 這個最小入口開始，一路看到怎麼自己寫工具給代理人用、六步驟的權限判定順序怎麼保護你的檔案、怎麼用程式碼定義子代理人，還有一票只有真的寫下去才會踩到的坑。你不一定要現在就把每一節都記住——這一章比較像一份「未來要動手時回來查」的參考地圖：什麼時候該用 allowedTools、什麼時候該寫 canUseTool、子代理人的 frontmatter 有哪些欄位，都留在這裡等你。真要動手時，先回 12.2 跑一次最小範例，跑得動、有感覺了，再一節一節往下挑需要的部分讀。接下來我們要進入本書的「大師篇」，從第 14 章的 Context 工程開始，看更底層的東西——Claude 怎麼管理它看到的那些資訊。