使用 Agent SDK

Agent SDK 不是“在程式碼裡呼叫一次模型”，而是把 Claude Code 的 agent loop、工具執行、上下文管理和許可權機制放進你的程式。日常寫程式碼用 CLI；要做產品、服務、CI agent 或內部平臺，才進入 SDK。——翔宇

1. 先改名：Claude Code SDK 已更名為 Claude Agent SDK

官方文件已經明確：舊的 Claude Code SDK 更名為 Claude Agent SDK。

當前包名：

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

TypeScript SDK 會透過 optional dependency 帶平臺對應的 Claude Code native binary，所以不一定需要另裝 Claude Code CLI。

2. Agent SDK 解決什麼問題

普通 Anthropic Client SDK 是你自己實現 tool loop：

• 傳送 prompt。
• 模型返回 tool use。
• 你執行工具。
• 再把 tool result 發回模型。
• 迴圈直到完成。

Agent SDK 是 Claude Code 替你跑 agent loop：

• Claude 自主讀檔案。
• 搜尋程式碼。
• 執行命令。
• 編輯檔案。
• 呼叫 MCP。
• 使用 Hooks、Skills、Subagents。
• 管理上下文和 sessions。
• 流式返回訊息、工具呼叫和結果。

flowchart TD
    Prompt["你的程式傳送任務"]
    Loop["Agent SDK agent loop"]
    Decide["Claude 決定下一步"]
    Tools["讀檔案 / 搜尋 / Bash / Edit / MCP"]
    Observe["觀察工具結果"]
    Done["返回結果或結構化輸出"]

    Prompt --> Loop
    Loop --> Decide
    Decide --> Tools
    Tools --> Observe
    Observe --> Decide
    Decide --> Done

    style Loop fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Tools fill:#e0f2fe,stroke:#0284c7,stroke-width:2px

3. 什麼時候用 SDK，什麼時候不用

用 Claude Code CLI：

• 日常寫程式碼。
• 一次性除錯。
• 互動式重構。
• 需要你邊看邊確認。
• 還沒跑穩的工作流。

用 Agent SDK：

• CI / CD 自動修復。
• 後臺 worker。
• 內部程式碼平臺。
• Web app 裡的 coding agent。
• 需要程式化審批、日誌、計費、會話管理。
• 需要把 Claude Code 的工具能力接進自己的系統。

用 Managed Agents：

• 你不想維護 agent 執行環境和 sandbox。
• 需要託管事件流、長任務、非同步 session。
• 生產級 agent 更適合交給 Anthropic 管執行環境。

4. 安裝和認證

TypeScript：

npm install @anthropic-ai/claude-agent-sdk

Python：

pip install claude-agent-sdk

基礎認證是 API key：

export ANTHROPIC_API_KEY=your-api-key

也支援第三方 provider：

• Amazon Bedrock：設定 CLAUDE_CODE_USE_BEDROCK=1 並配置 AWS credentials。
• Google Vertex AI：設定 CLAUDE_CODE_USE_VERTEX=1 並配置 Google Cloud credentials。
• Microsoft Azure AI Foundry：設定 CLAUDE_CODE_USE_FOUNDRY=1 並配置 Azure credentials。

官方同時說明：除非事先獲批，第三方開發者不能把 claude.ai 登入或 claude.ai rate limits 提供給自己的產品使用者。對外產品應使用 API key 認證方式。

5. 最小 Python 示例

from claude_agent_sdk import ClaudeAgentOptions, query
from asyncio import run


async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(
            allowed_tools=["Bash", "Glob"],
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


run(main())

這裡的重點：

• prompt 是任務。
• ClaudeAgentOptions 控制工具、許可權、MCP、系統提示詞等。
• async for 會持續接收 agent 思考、工具呼叫、結果訊息。
• allowed_tools 預批准工具，不等於停用其他工具。

6. 最小 TypeScript 示例

const { query } = await import("@anthropic-ai/claude-agent-sdk");

for await (const message of query({
  prompt: "Find all places that import the auth module.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

TypeScript 和 Python 的概念一致，但欄位命名不同：

• Python：allowed_tools、permission_mode、setting_sources、output_format
• TypeScript：allowedTools、permissionMode、settingSources、outputFormat

7. 內建工具能力

Agent SDK 帶 Claude Code 的常用工具。

• Read：讀取檔案。
• Write：建立檔案。
• Edit：精確修改檔案。
• Bash：執行 shell 命令、指令碼、git 操作。
• Monitor：監聽後臺指令碼輸出並按事件處理。
• Glob：按 pattern 找檔案。
• Grep：用 regex 搜尋檔案內容。
• WebSearch：搜尋網頁。
• WebFetch：讀取網頁內容。
• AskUserQuestion：向使用者提問。

最容易犯的錯是直接給全工具：

ClaudeAgentOptions(
    permission_mode="bypassPermissions",
)

這會讓 agent 在你的程序環境裡擁有極大能力。生產環境應該從最小工具面開始。

8. Permissions：SDK 裡的安全鏈路

SDK 許可權評估順序官方寫得很清楚：

1. Hooks 先執行。
2. Deny rules 先檢查，包括 disallowed_tools 和 settings deny。
3. Permission mode 生效。
4. Allow rules 檢查，包括 allowed_tools 和 settings allow。
5. 還沒決定時呼叫 canUseTool callback。

常見模式：

ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
)

這會構成一個比較乾淨的只讀 agent：

• Read、Glob、Grep 被批准。
• 其他工具不會彈出視窗，而是直接拒絕。

要阻止工具，用 disallowed_tools：

ClaudeAgentOptions(
    disallowed_tools=["Bash", "Write", "Edit"],
)

9. Permission modes 怎麼選

SDK 支援的主要模式：

• default：標準許可權行為，未匹配工具會走 canUseTool。
• dontAsk：未預批准工具直接拒絕。
• acceptEdits：自動接受檔案編輯和常見檔案系統操作。
• bypassPermissions：繞過大多數許可權提示，風險極高。
• plan：規劃模式，不執行工具。
• auto：TypeScript 支援，模型分類器審批工具呼叫。

選擇建議：

• 只讀分析：allowed_tools=["Read", "Glob", "Grep"] + dontAsk。
• 原型期自動改程式碼：acceptEdits，但只在隔離目錄或臨時分支。
• 生產後臺 agent：避免 bypassPermissions，顯式 allow / deny。
• 使用者要先批准方案：先 plan，確認後再切到執行模式。

SDK 支援執行中改模式：

await q.set_permission_mode("acceptEdits")

10. Settings 和專案配置

Agent SDK 可以讀取 Claude Code 的 filesystem-based configuration。

預設 query() 會讀取：

• 當前 working directory 裡的 .claude/
• 使用者目錄裡的 ~/.claude/

它能用到：

• Skills：.claude/skills/*/SKILL.md
• Custom commands：.claude/commands/*.md
• Memory：CLAUDE.md 或 .claude/CLAUDE.md
• Plugins：透過 options 程式化傳入
• Project settings：例如 permissions、hooks、MCP 等

如果你想限制來源，設定：

• Python：setting_sources
• TypeScript：settingSources

11. Sessions：繼續、恢復和 fork

Session 是 agent 工作時累積的會話歷史，包含：

• prompt。
• tool calls。
• tool results。
• Claude responses。
• agent 做過的分析。

Session 會自動寫到磁碟。恢復 session 意味著 agent 拿回之前完整上下文。

三種常見方式：

• Continue：繼續當前目錄最近 session。
• Resume：用 session ID 恢復指定 session。
• Fork：複製一個 session 的歷史，開一個新分支嘗試不同方向。

重要邊界：

• Session 儲存對話歷史，不儲存檔案系統快照。
• 要撤銷檔案變更，用 checkpointing，不是 session resume。
• 多使用者產品裡不要只用“最近 session”，要按使用者或任務儲存 session ID。

12. Streaming：不要只等最終文本

SDK 是流式的。你可以在 agent 工作過程中收到：

• system init。
• assistant message。
• tool use。
• tool result。
• permission request。
• result message。
• usage / cost 資訊。

這對產品化很關鍵：

• UI 可以展示 agent 當前在做什麼。
• 後端可以即時記錄工具呼叫。
• 使用者可以在中途批准或拒絕。
• 失敗時可以定位卡在哪一步。

13. 結構化輸出

自由文本適合聊天，不適合程式使用。

SDK 支援結構化輸出：

• TypeScript：outputFormat
• Python：output_format

你定義 JSON Schema，agent 可以先多輪工具呼叫，最後返回經過驗證的 JSON。

TypeScript 示例：

const { query } = await import("@anthropic-ai/claude-agent-sdk");

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    risk_level: { enum: ["low", "medium", "high"] },
    files: {
      type: "array",
      items: { type: "string" },
    },
  },
  required: ["summary", "risk_level"],
};

for await (const message of query({
  prompt: "Review the current changes and return a risk summary.",
  options: {
    outputFormat: {
      type: "json_schema",
      schema,
    },
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.structured_output);
  }
}

官方說明：如果校驗失敗，SDK 會重試；重試後仍失敗，會返回錯誤 subtype，而不是偽造結構化資料。

14. 自定義工具和 MCP

Agent SDK 有兩種擴充套件工具的方式。

第一種：MCP server。

ClaudeAgentOptions(
    mcp_servers={
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"],
        }
    }
)

適合：

• 資料庫。
• 瀏覽器自動化。
• 外部 API。
• 組織內工具。
• 已經有 MCP server 的系統。

第二種：SDK in-process MCP server。

你可以把自己程式裡的函式定義成 tool，再傳給 agent。官方把這稱為 custom tools，透過 SDK 的 in-process MCP server 暴露。

適合：

• 應用內部函式。
• 受控業務 API。
• 不想啟動額外程序的工具。
• 需要型別化輸入 schema 的能力。

15. Subagents in SDK

SDK 可以定義和呼叫 Subagents。

Python 示例概念：

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="Reviews code quality, security risks, and missing tests.",
            prompt="Analyze code quality and return findings ordered by severity.",
            tools=["Read", "Glob", "Grep"],
        )
    },
)

關鍵點：

• 要讓主 agent spawn subagents，需要把 Agent 加進 allowed_tools / allowedTools。
• Subagent 有自己的工具邊界。
• Subagent 訊息裡會有 parent_tool_use_id，方便追蹤屬於哪次 subagent 呼叫。
• Subagents 不會自動繼承父 agent 的所有許可權。

16. Hooks in SDK

SDK hooks 可以用 callback 函式控制 agent 生命週期。

常見用途：

• 記錄檔案修改。
• 阻止危險 Bash。
• 審計 tool use。
• 在 Stop 前檢查結果。
• 對 permission request 做程式化審批。

Python 裡可用 hook events 和 TypeScript 不完全一樣。官方說明 TypeScript 支援更多事件，例如 SessionStart、SessionEnd、Setup、ConfigChange、WorktreeCreate、WorktreeRemove、PostToolBatch 等；Python 當前支援核心事件集合。

17. Skills、Slash commands 和 Plugins

SDK 可以使用 Claude Code 的一些擴充套件能力：

• Skills：Markdown 定義的專用能力。
• Slash commands：自定義 command。
• Plugins：透過 options 程式化接入。

邊界：

• SKILL.md 裡的 allowed-tools frontmatter 只在 Claude Code CLI 直接使用 Skills 時支援；SDK 裡應透過主 options 控制 tools。
• 不要把 SDK 產品的安全邊界放到 Skill frontmatter 裡。
• Plugins 適合複用擴充套件，但生產服務要固定版本和來源。

18. AskUserQuestion 和審批

SDK 裡的 agent 可能需要使用者輸入：

• 澄清需求。
• 審批工具呼叫。
• 選擇方案。
• 確認風險。

Claude Code 提供 AskUserQuestion 工具，SDK 也有處理 approvals 和 user input 的機制。

產品設計上不要讓 agent 卡死在“需要人類批准”：

• UI 要展示等待狀態。
• 後端要能超時。
• 許可權請求要記錄。
• 多使用者場景要把請求路由給正確使用者。
• 無人值守任務用 dontAsk，讓未批准工具直接拒絕。

19. Observability 和成本

生產 agent 必須可觀測。

至少記錄：

• session ID。
• 使用者或任務 ID。
• prompt 摘要。
• tool calls。
• permission decisions。
• structured output 是否成功。
• error subtype。
• usage / cost。
• latency。

Agent SDK 官方提供 usage / cost tracking 和 OpenTelemetry 相關文件。不要等線上出問題才補日誌。

20. Checkpointing 和檔案安全

Session 不是檔案快照。Agent 改檔案後，如果你需要可回復能力，要用 checkpointing 或自己在執行環境外做版本控制。

最低要求：

• 每個任務獨立工作目錄。
• 執行前記錄 git status。
• 改完後儲存 diff。
• 跑測試。
• 審批後再合併。
• 出錯可清理臨時目錄。

對後臺服務，推薦用：

• 臨時 clone。
• 臨時 branch。
• git worktree。
• 容器或 sandbox。
• 最小許可權 token。

21. 部署邊界

SDK agent 執行在你的程序和基礎設施裡，所以你負責：

• API key 管理。
• 檔案系統隔離。
• 網路訪問策略。
• shell 命令邊界。
• 多租戶隔離。
• 日誌脫敏。
• 成本限制。
• 超時和重試。
• worker 佇列。
• sandbox 或容器。
• 版本升級。

Managed Agents 則是 Anthropic 託管 agent 和 sandbox。官方 overview 裡也建議：一個常見路徑是先用 Agent SDK 本地原型驗證，再遷到 Managed Agents 做生產託管。

22. 品牌和合規邊界

官方 branding guidance 裡提到，整合 Claude Agent SDK 時可以用：

• “Claude Agent”
• “Claude”
• “Powered by Claude”

不應使用：

• “Claude Code”
• “Claude Code Agent”
• 模仿 Claude Code 的品牌視覺或 ASCII art。

這對公開產品、客戶介面、選單命名都重要。

23. 推薦落地順序

不要一上來就寫生產 agent。按這個順序：

1. 在 Claude Code CLI 裡跑通流程。
2. 收斂工具和許可權邊界。
3. 寫最小 SDK demo，只給只讀工具。
4. 加 session ID 和日誌。
5. 加審批或 dontAsk。
6. 加結構化輸出。
7. 接 MCP 或 custom tools。
8. 加 Hooks 做審計和阻斷。
9. 用隔離工作區處理檔案修改。
10. 加成本、超時、重試和佇列。
11. 再考慮對外產品或 Managed Agents。

24. 常見故障：SDK 跑不起來

排查順序：

1. 確認包名是 claude-agent-sdk 或 @anthropic-ai/claude-agent-sdk。
2. 確認 ANTHROPIC_API_KEY 已設定。
3. 如果用 Bedrock / Vertex / Foundry，確認環境變數和雲憑據。
4. TypeScript 場景檢查 optional native binary 是否安裝成功。
5. 確認 Python / Node 版本符合專案要求。
6. 先跑官方最小 query 示例，不要一開始接 MCP 和 Hooks。
7. 開啟 debug log，看 API error、許可權 error、工具 error 屬於哪類。

25. 常見故障：許可權行為和預期不同

常見原因：

• 以為 allowed_tools 會限制所有工具。
• 同時用了 allowed_tools 和 bypassPermissions。
• 沒有設定 dontAsk，導致未匹配工具進入 canUseTool。
• setting_sources 排除了 project，專案 .claude/settings.json 沒載入。
• Subagent 繼承了父會話危險 permission mode。
• Hook 在許可權鏈前面已經 allow / deny 了。

處理：

• 明確使用 disallowed_tools。
• 鎖定工具面時用 permission_mode="dontAsk"。
• 避免生產使用 bypassPermissions。
• 檢查 setting sources。
• 給 subagents 單獨工具邊界。
• 記錄 permission decision。

26. 常見故障：結果不能給程式用

表現：

• 輸出是自然語言，程式解析不穩定。
• 欄位缺失。
• JSON 格式偶發錯誤。
• 長任務後只返回總結，沒有結構化欄位。

處理：

• 使用 structured outputs。
• 縮小 schema。
• 把可選欄位設 optional。
• 在 prompt 裡說明任務目標和資料來源。
• 檢查 error_max_structured_output_retries。
• 不要手寫正則解析自然語言輸出。

27. 自檢清單

學完這一章，你應該能做到：

• 我知道 Claude Code SDK 已更名為 Claude Agent SDK。
• 我能解釋 Agent SDK、Client SDK、Claude Code CLI、Managed Agents 的區別。
• 我知道什麼時候該先用 CLI，而不是直接 SDK。
• 我能寫出最小 Python 或 TypeScript query 示例。
• 我知道 API key、Bedrock、Vertex、Foundry 的認證入口。
• 我知道 allowed_tools 是預批准，不是限制。
• 我知道 dontAsk、acceptEdits、bypassPermissions、plan 的取捨。
• 我知道 session 儲存對話歷史，不儲存檔案快照。
• 我知道 structured outputs 適合程式化結果。
• 我知道 SDK 可以接 MCP、自定義 tools、Hooks、Subagents、Skills。
• 我知道生產 SDK agent 要有日誌、成本、隔離、審批和回復。

28. 術語速查

• Claude Agent SDK：把 Claude Code agent loop 作為 Python / TypeScript 庫使用的 SDK。
• query()：啟動一次 agent 任務的核心介面。
• ClaudeAgentOptions：Python SDK 的配置物件。
• Options：TypeScript SDK 的配置物件。
• allowed_tools / allowedTools：預批准工具列表。
• disallowed_tools / disallowedTools：拒絕工具列表。
• permission_mode / permissionMode：工具許可權模式。
• canUseTool：執行時審批工具呼叫的 callback。
• session：SDK 儲存的 agent 會話歷史。
• resume：用 session ID 恢復指定會話。
• continue：繼續當前目錄最近會話。
• fork：從已有 session 歷史複製出新分支。
• output_format / outputFormat：結構化輸出配置。
• structured_output：校驗透過後的結構化結果。
• mcp_servers / mcpServers：接入 MCP server 的配置。
• AgentDefinition：SDK 中定義 subagent 的結構。
• setting_sources / settingSources：限制 SDK 載入哪些 filesystem settings。
• OpenTelemetry：生產觀測和 tracing 體系。
• Managed Agents：Anthropic 託管 agent 和 sandbox 的產品形態。

29. 官方資料

• Agent SDK overview
• Quickstart
• How the agent loop works
• Use Claude Code features in the SDK
• Configure permissions
• Work with sessions
• Get structured output from agents
• Give Claude custom tools
• Hosting the Agent SDK