Feb 23, 2026

Claude Agent SDK 完整指南：從 Built-in Tools 到 Subagents 的全面解析

Claude Agent SDK（前身為 Claude Code SDK）讓開發者能夠以 Claude Code 作為函式庫，建構具有自主讀檔、執行指令、搜尋網路、編輯程式碼能力的 AI Agent。同時提供 Python 和 TypeScript 兩種語言的 SDK。本文將全面解析 Agent SDK 的核心能力和使用模式。

一、核心概念

Agent SDK 將 Claude Code 的所有能力封裝為可程式化的介面。與 Client SDK 不同，Agent SDK 內建工具執行能力，開發者不需要自行實作工具呼叫迴圈：

# Client SDK：需要自行實作工具迴圈
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK：Claude 自主處理工具
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

安裝與設定

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

# Python
pip install claude-agent-sdk

設定 API key：

export ANTHROPIC_API_KEY=your-api-key

也支援 Amazon Bedrock、Google Vertex AI 和 Microsoft Azure 的第三方 API 提供者認證。

二、Built-in Tools：內建工具

Agent SDK 提供開箱即用的工具集：

工具	功能
Read	讀取工作目錄中的任何檔案
Write	建立新檔案
Edit	精確編輯現有檔案
Bash	執行終端指令、腳本、git 操作
Glob	以模式匹配尋找檔案
Grep	以正則表達式搜尋檔案內容
WebSearch	搜尋網路取得最新資訊
WebFetch	擷取和解析網頁內容
AskUserQuestion	向使用者提出多選澄清問題

透過 allowed_tools 控制 agent 可使用的工具：

async for message in query(
    prompt="Find all TODO comments and create a summary",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
    if hasattr(message, "result"):
        print(message.result)

三、Hooks：生命週期鉤子

Hooks 讓開發者在 agent 生命週期的關鍵點執行自定義程式碼，用於驗證、記錄、阻擋或轉換 agent 行為。

可用的 Hooks：PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit 等。

審計日誌範例

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

async for message in query(
    prompt="Refactor utils.py to improve readability",
    options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        hooks={
            "PostToolUse": [
                HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
            ]
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Hooks 使用正則表達式匹配器來選擇要攔截的工具呼叫，提供靈活的過濾能力。

四、Subagents：子代理

可以產生專門化的子代理來處理聚焦的子任務。主代理委派工作，子代理完成後回報結果。

定義自定義 Agent

在 allowed_tools 中包含 Task 以啟用子代理功能：

async for message in query(
    prompt="Use the code-reviewer agent to review this codebase",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Task"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Expert code reviewer for quality and security reviews.",
                prompt="Analyze code quality and suggest improvements.",
                tools=["Read", "Glob", "Grep"],
            )
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

子代理的訊息包含 parent_tool_use_id 欄位，用於追蹤哪些訊息屬於哪個子代理的執行。

五、MCP 整合

透過 Model Context Protocol 連接到外部系統：資料庫、瀏覽器、API 等。

Playwright 瀏覽器自動化範例

async for message in query(
    prompt="Open example.com and describe what you see",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {
                "command": "npx",
                "args": ["@playwright/mcp@latest"]
            }
        }
    ),
):
    if hasattr(message, "result"):
        print(message.result)

MCP 伺服器以字典格式定義，key 為伺服器名稱，value 包含 command 和 args。Agent SDK 會自動管理 MCP 連線。

六、Permissions：權限控制

精確控制 agent 可使用的工具，允許安全操作、阻擋危險操作，或要求敏感操作的審批。

唯讀 Agent 範例

async for message in query(
    prompt="Review this code for best practices",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
        permission_mode="bypassPermissions"
    ),
):
    if hasattr(message, "result"):
        print(message.result)

permission_mode 選項：

bypassPermissions：跳過所有權限提示（適合受控環境）
acceptEdits：自動接受檔案編輯（適合需要修改檔案的 agent）
其他模式提供更細緻的控制

七、Sessions：工作階段管理

維持跨多次交互的 context。Claude 記住讀過的檔案、做過的分析和對話歷史。可以恢復工作階段或分岔探索不同方向。

恢復工作階段範例

session_id = None

# 第一次查詢：捕獲 session ID
async for message in query(
    prompt="Read the authentication module",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if hasattr(message, "subtype") and message.subtype == "init":
        session_id = message.session_id

# 以完整 context 恢復
async for message in query(
    prompt="Now find all places that call it",
    options=ClaudeAgentOptions(resume=session_id),
):
    if hasattr(message, "result"):
        print(message.result)

第二次查詢中的 "it" 指的是第一次讀取的 auth module，因為恢復了完整的 session context。

八、Claude Code 功能整合

SDK 也支援 Claude Code 的檔案系統配置。設定 setting_sources=["project"] 以啟用：

功能	說明	位置
Skills	Markdown 定義的專門能力	`.claude/skills/SKILL.md`
Slash Commands	常用任務的自定義指令	`.claude/commands/*.md`
Memory	專案 context 和指令	`CLAUDE.md` 或 `.claude/CLAUDE.md`
Plugins	擴展自定義指令、agent 和 MCP 伺服器	透過 `plugins` 選項程式化配置

九、Agent SDK vs Client SDK vs Claude Code CLI

vs Client SDK

Client SDK 提供直接的 API 存取，開發者自行實作工具執行。Agent SDK 提供 Claude 加上內建的工具執行能力。

面向	Client SDK	Agent SDK
工具執行	開發者自行實作	SDK 內建
工具迴圈	手動管理	自動處理
內建工具	無	Read、Write、Edit、Bash 等
適用場景	簡單的 API 呼叫	自主 Agent 建構

vs Claude Code CLI

相同能力，不同介面：

使用場景	最佳選擇
互動式開發	CLI
CI/CD 管線	SDK
自定義應用程式	SDK
一次性任務	CLI
生產自動化	SDK

許多團隊兩者並用：CLI 用於日常開發，SDK 用於生產環境。工作流程可在兩者之間直接轉換。

十、品牌指引

使用 Claude Agent SDK 的合作夥伴，品牌使用是選用的。允許的稱呼：

"Claude Agent"（下拉選單中的首選）
"Claude"（在已標記為 "Agents" 的選單中）
"{YourAgentName} Powered by Claude"

不允許使用 "Claude Code" 或 "Claude Code Agent"，也不允許使用模仿 Claude Code 的 ASCII art 或視覺元素。

總結

Claude Agent SDK 將 Claude Code 的全部能力封裝為可程式化的介面，讓開發者能夠建構具備自主工具使用能力的 AI Agent。從內建的檔案操作和指令執行工具，到 Hooks 生命週期控制、Subagents 子代理委派、MCP 外部系統整合，再到 Sessions 的 context 持久化，Agent SDK 提供了建構生產級 AI Agent 所需的完整能力棧。與 Client SDK 相比，Agent SDK 大幅減少了工具整合的樣板程式碼；與 Claude Code CLI 相比，SDK 更適合程式化控制和生產自動化場景。