---
title: "使用 Agent SDK"
description: "用 Claude Agent SDK 呼叫 Claude Code agent loop，覆蓋認證、許可權、會話、MCP、Hooks、Subagents 和部署邊界。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-05"
---

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

> [!NOTE]
> **這一章用 17 分鐘換什麼**：這一組前面已經講完 Skills、Subagents、Hooks、Commands。Agent SDK 是最後一層：把這些能力程式化。讀完你應該能判斷什麼時候該用 SDK，怎麼安裝認證，怎麼控制工具和許可權，怎麼處理 session、結構化輸出、MCP、Hooks、Subagents、觀測和部署安全。

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

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

當前包名：

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

```bash
pip install claude-agent-sdk
```

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

> [!IMPORTANT]
> **搜尋資料時注意名稱**：老文章可能還叫 Claude Code SDK；官方當前口徑是 Claude Agent SDK。

## 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。
- 流式返回訊息、工具呼叫和結果。

```mermaid
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
```

> [!IMPORTANT]
> **第一性原理**：Client SDK 是“模型 API + 你自己寫工具迴圈”；Agent SDK 是“Claude Code 的工具迴圈作為庫”；Managed Agents 是 Anthropic 託管 agent 和 sandbox。

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

用 Claude Code CLI：

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

用 Agent SDK：

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

用 Managed Agents：

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

> [!TIP]
> **先 CLI，後 SDK**：如果一個流程在 CLI 裡還跑不穩，不要急著寫進 SDK。程式碼會把不確定性固化。

## 4. 安裝和認證

TypeScript：

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

Python：

```bash
pip install claude-agent-sdk
```

基礎認證是 API key：

```bash
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 認證方式。

> [!CAUTION]
> **不要把本地 CLI 登入當產品認證**：SDK 產品要走 API key 或官方支援的雲 provider 憑據，不能把你的 claude.ai 賬號能力轉賣或轉借給使用者。

## 5. 最小 Python 示例

```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` 預批准工具，不等於停用其他工具。

> [!TIP]
> **第一次寫 SDK agent 先只給只讀工具**：例如 `Read`、`Glob`、`Grep`。確認行為穩定後再給 `Edit`、`Write`、`Bash`。

## 6. 最小 TypeScript 示例

```ts
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`

> [!WARNING]
> **不要混用欄位風格**：Python 用 snake_case；TypeScript 用 camelCase。

## 7. 內建工具能力

Agent SDK 帶 Claude Code 的常用工具。

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

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

```python
ClaudeAgentOptions(
    permission_mode="bypassPermissions",
)
```

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

> [!CAUTION]
> **SDK 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。

常見模式：

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

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

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

要阻止工具，用 `disallowed_tools`：

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

> [!IMPORTANT]
> **`allowed_tools` 不是沙盒**：它只是預批准。要鎖死工具面，用 `permission_mode="dontAsk"` 或 `disallowed_tools`。

## 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 支援執行中改模式：

```python
await q.set_permission_mode("acceptEdits")
```

> [!WARNING]
> **`bypassPermissions` 不受 `allowed_tools` 限制**：如果同時寫 `allowed_tools=["Read"]` 和 `bypassPermissions`，仍然會批准其他工具。要阻止必須寫 deny。

## 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`

> [!TIP]
> **生產服務不要盲讀工作目錄配置**：多租戶或 CI 場景下，要明確哪些 setting sources 可以載入，避免儲存庫配置擴大許可權。

## 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。

> [!IMPORTANT]
> **Session 不是資料庫事務**：它能恢復 agent 的記憶，不能自動回復 agent 改過的檔案。

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

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

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

這對產品化很關鍵：

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

> [!TIP]
> **生產 UI 不要只顯示最後結果**：至少要展示“正在讀檔案 / 正在執行測試 / 等待審批 / 已完成”這類狀態。

## 13. 結構化輸出

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

SDK 支援結構化輸出：

- TypeScript：`outputFormat`
- Python：`output_format`

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

TypeScript 示例：

```ts
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，而不是偽造結構化資料。

> [!TIP]
> **結構化輸出 schema 要小**：欄位越多、巢狀越深、required 越多，越容易失敗。先從最小可用結構開始。

## 14. 自定義工具和 MCP

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

第一種：MCP server。

```python
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 的能力。

> [!IMPORTANT]
> **工具越貼近業務，許可權越要明確**：讀操作、寫操作、刪除操作分開建 tool，不要做一個萬能 `execute`。

## 15. Subagents in SDK

SDK 可以定義和呼叫 Subagents。

Python 示例概念：

```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 的所有許可權。

> [!WARNING]
> **給 SDK agent 開 Agent tool 前先限制 agent 型別**：不要讓一個後臺服務隨意 spawn 任意 worker。

## 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 當前支援核心事件集合。

> [!TIP]
> **SDK hooks 適合產品治理**：比 shell hooks 更容易接你的日誌、資料庫、許可權系統和業務審批。

## 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 適合複用擴充套件，但生產服務要固定版本和來源。

> [!IMPORTANT]
> **SDK 裡安全控制回到 options 和 permissions**：Skill 可以提供流程，不能替代服務端許可權。

## 18. AskUserQuestion 和審批

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

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

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

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

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

> [!CAUTION]
> **Headless agent 不該預設等待人類**：後臺任務要麼預批准工具，要麼用 `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 相關文件。不要等線上出問題才補日誌。

> [!TIP]
> **日誌別記完整敏感內容**：記錄後設資料、檔案路徑、工具名和錯誤類別；金鑰、prompt 全文、diff 全文要謹慎處理。

## 20. Checkpointing 和檔案安全

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

最低要求：

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

對後臺服務，推薦用：

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

> [!WARNING]
> **不要讓生產 SDK agent 直接改主儲存庫工作區**：隔離目錄和可回復 diff 是基本要求。

## 21. 部署邊界

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

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

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

> [!IMPORTANT]
> **SDK 是自託管責任**：你得到更強控制權，也承擔更多安全、運維和合規責任。

## 22. 品牌和合規邊界

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

- “Claude Agent”
- “Claude”
- “Powered by Claude”

不應使用：

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

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

> [!TIP]
> **對外產品叫 Claude Agent 更穩**：不要把自己的產品包裝成 Claude Code 官方客戶端。

## 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。

> [!TIP]
> **先做可觀察，再做自動化**：你看不見 agent 做什麼時，自動化越強風險越大。

## 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 屬於哪類。

> [!TIP]
> **先最小化**：prompt + `Read` / `Glob` 跑通，再逐步加工具、MCP、Hooks、sessions。

## 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。

> [!WARNING]
> **許可權排障看評估順序**：Hooks、deny、mode、allow、callback。不要只盯 `allowed_tools`。

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

表現：

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

處理：

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

> [!IMPORTANT]
> **程式消費就用結構化輸出**：不要把自由文本當 API contract。

## 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](https://code.claude.com/docs/en/agent-sdk/overview)
- [Quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart)
- [How the agent loop works](https://code.claude.com/docs/en/agent-sdk/agent-loop)
- [Use Claude Code features in the SDK](https://code.claude.com/docs/en/agent-sdk/claude-code-features)
- [Configure permissions](https://code.claude.com/docs/en/agent-sdk/permissions)
- [Work with sessions](https://code.claude.com/docs/en/agent-sdk/sessions)
- [Get structured output from agents](https://code.claude.com/docs/en/agent-sdk/structured-outputs)
- [Give Claude custom tools](https://code.claude.com/docs/en/agent-sdk/custom-tools)
- [Hosting the Agent SDK](https://code.claude.com/docs/en/agent-sdk/hosting)

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/02-extensions-automation/commands" title="Commands（上一篇）" description="Commands 是互動入口；Agent SDK 是程式化入口。兩者背後都可以使用 Skills、MCP、Hooks 和 permissions。" />
  <Card href="/zh-Hant/docs/claude-code/official/02-extensions-automation/extension-map" title="擴充套件能力地圖" description="回到總圖，覆盤 CLAUDE.md、Rules、Skills、MCP、Subagents、Hooks、Commands、Plugins、Agent SDK 的分工。" />
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/permissions" title="管理許可權" description="SDK 產品化時，許可權鏈路是核心風險點。回看 allow、deny、ask 和 permission modes。" />
</Cards>
