Claude Code SDK：Python 與 TypeScript 開發者指南

Claude Code SDK（現正式命名為 Claude Agent SDK）是一個 Python 和 TypeScript 函式庫，讓你可以在自己的應用程式中將 Claude 作為自主代理運行。你提供提示，它就會處理其餘工作：讀取檔案、執行命令、編輯程式碼，並反覆迭代直到任務完成。無需編寫工具循環，也無需管理串流處理。

本指南涵蓋開發者入門所需的一切：安裝、核心 query() API、內建工具、鉤子、會話、子代理、MCP 整合，以及如何使用 Novita AI 的 LLM API 作為模型後端。

重點摘要

• Claude Code SDK 現在改名為 Claude Agent SDK（Python 的 claude-agent-sdk，TypeScript 的 @anthropic-ai/claude-agent-sdk）。
• 單一 query() 函數取代了使用 Anthropic Client SDK 時需要手動實作的工具執行循環。
• 內建工具涵蓋檔案讀取、編輯、Bash 執行、網路搜尋等 — 無需自行實作。
• 會話可讓代理在多次呼叫之間繼續工作，並保留完整的上下文。
• 鉤子讓你在特定的生命週期階段驗證、記錄或封鎖工具呼叫。
• Novita AI 的 Anthropic 相容端點（https://api.novita.ai/anthropic）讓你使用相同的 SDK 程式碼來調用高品質的開放權重模型。

什麼是 Claude Code SDK？

Claude Code SDK 是 Claude Code 代理能力的程式化介面。它暴露了 Claude Code CLI 在互動模式下使用的相同工具、推理循環和上下文管理 — 但以函式庫的形式讓你可以從自己的程式碼中匯入和呼叫。

Anthropic 在 4.6 代開始將其重新命名為 Claude Agent SDK，但原始的搜尋詞「claude code sdk」仍然準確描述了它的本質：位於 Claude Code 之上的 SDK 層，讓你能以軟體方式自動化代理任務。

適用場景：

• 在 CI/CD 中自動進行程式碼審查、重構或測試生成
• 代理為你讀取和修改檔案、執行腳本或搜尋網路
• 多代理管線，協調者將子任務委派給專業工作者
• 任何希望 Claude 自主執行多步驟操作（不僅是回答提示）的工作流程

不適用場景： 如果你需要直接控制每一條訊息、從單一呼叫中獲得結構化輸出，或是為聊天 UI 串流回應，那麼 Anthropic Client SDK 更為合適。

Claude Code SDK 與 Anthropic Client SDK：何時使用哪一個

兩個 SDK 都建立在 Claude 之上，但它們解決的問題不同。

	Claude Agent SDK	Anthropic Client SDK
工具執行	由 Claude 自主處理	你實作工具循環
介面	query() 返回非同步迭代器	client.messages.create() 返回回應物件
內建工具	Read、Write、Edit、Bash、Grep、Glob、WebSearch 等	無 — 你定義並執行所有工具
會話	內建 — 使用會話 ID 恢復	手動 — 自行管理對話歷史
最適合	代理管線、CI/CD、檔案操作	聊天應用、結構化輸出、精細控制

如果你想讓 Claude 自主決定讀取哪些檔案並編輯它們：使用 Agent SDK。如果你希望 Claude 回應特定提示並返回一個值讓你處理：使用 Client SDK。

安裝 Claude Agent SDK

Python（需要 Python 3.10+）：

pip install claude-agent-sdk

TypeScript / Node.js：

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

TypeScript 套件會將平台專屬的原生 Claude Code 二進位檔作為可選依賴項捆綁。你不需要單獨安裝 Claude Code。

安裝前驗證你的 Python 版本：

python3 --version  # macOS/Linux
py --version       # Windows

如果 pip 回報 No matching distribution found for claude-agent-sdk，表示你的 Python 直譯器版本低於 3.10。

步驟 1：設定驗證

將你的 Anthropic API 金鑰設定為環境變數：

export ANTHROPIC_API_KEY=your-api-key

SDK 也支援 Amazon Bedrock、Google Vertex AI 和 Azure AI Foundry，適合透過雲端供應商路由的團隊：

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# 加上標準的 AWS 憑證

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# 加上 GOOGLE_CLOUD_PROJECT 和 gcloud 憑證

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# 加上 Azure 憑證

步驟 2：執行你的第一個代理查詢

整個 SDK 的介面圍繞一個單一函數構建：query()。它接受一個提示和選項，並返回一個訊息事件的非同步迭代器。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

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

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List all Python files in this directory",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

迭代器會產生幾種訊息類型。最實用的兩種：

• ResultMessage（或帶有 result 欄位的訊息）— 代理的最終回應
• 帶有 subtype === "init" 的 SystemMessage — 包含用於稍後恢復的 session_id

步驟 3：使用 allowedTools 控制權限

SDK 附帶預先實作好的工具。你宣告代理可以使用哪些工具；Claude 負責執行。

工具	作用
Read	讀取工作目錄中的任何檔案
Write	建立新檔案
Edit	對現有檔案進行有針對性的編輯
Bash	執行 shell 命令、腳本、git 操作
Glob	依模式尋找檔案（**/*.ts、src/**/*.py）
Grep	使用正規表示式搜尋檔案內容
WebSearch	搜尋網路以取得最新資訊
WebFetch	擷取並解析網頁內容
Monitor	監控背景腳本並對輸出行做出反應
AskUserQuestion	在任務進行中間使用者提問
Agent	調用已定義的子代理

Bash + Read + Edit 的組合足以應付大多數自動化程式碼任務。當代理需要外部資料時，可加入 WebSearch 或 WebFetch。

allowed_tools（Python） / allowedTools（TypeScript）會預先批准特定工具，無需提示。限制工具集也能限制代理可能無意中執行的操作 — 這對自動化管線來說是一個有用的防護措施。

唯讀程式碼審查代理：

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Review this codebase for security issues and code smell",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

完整編輯代理（預先批准檔案寫入）：

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" 會自動批准檔案編輯，無需互動式提示，這在 CI 中執行時是必需的。

步驟 4：使用鉤子進行生命週期控制

鉤子讓你在代理執行的特定階段執行自訂程式碼。你可以記錄動作、驗證輸入、阻止危險操作或更新外部狀態。

可用的鉤子事件： PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、Stop、SubagentStop、SubagentStart、PreCompact、Notification、PermissionRequest

以下範例在代理每次編輯或建立檔案時寫入稽核日誌：

import asyncio
from datetime import datetime
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().isoformat()}: modified {file_path}\n")
    return {}

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

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactor auth.ts to use interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

如果 PreToolUse 鉤子返回 { block: true }，將會完全阻止工具呼叫 — 這在自動化環境中對於執行「永不刪除檔案」等策略非常有用。

步驟 5：使用會話恢復工作

會話會保留代理的完整上下文 — 它讀取了哪些檔案、發現了什麼、對話歷史 — 跨越多次 query() 呼叫。這讓你可以將長任務分解為多個步驟，或繼續被中斷的工作。

若要恢復會話，請從 SystemMessage init 事件中擷取 session_id，然後將其傳遞給 resume：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # 第一次查詢：讀取並分析程式碼庫
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # 第二次查詢：帶著第一次的完整上下文繼續
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

第二個提示使用了「those dependencies」——這個引用之所以有效，是因為會話攜帶了來自第一次呼叫的上下文。如果沒有 resume，Claude 將完全不知道你在指什麼。

步驟 6：使用子代理委派任務

子代理是專門化的代理，你的主代理可以透過 Agent 工具來調用它們。主代理負責協調；子代理執行專門的工作。結果會回傳到主上下文。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

將 "Agent" 加入 allowed_tools 以預先批准子代理調用。來自子代理的訊息包含 parent_tool_use_id 欄位，因此你可以追蹤哪個輸出來自哪個子代理。

步驟 7：透過 MCP 連接外部系統

模型上下文協定（MCP）讓你可以為代理添加外部能力 — 資料庫、瀏覽器、內部 API — 而無需編寫自訂工具。代理會將 MCP 工具視為內建工具來使用。

以下範例透過 Playwright MCP 伺服器添加瀏覽器自動化：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

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

asyncio.run(main())

mcp_servers 選項接受任何遵循 MCP 規範的伺服器。社群 MCP 註冊表位於 github.com/modelcontextprotocol/servers，列出了數百種整合，包括 Postgres、Puppeteer、Slack、GitHub 和檔案系統變體。

使用 Novita AI 作為模型後端

Claude Agent SDK 預設使用 Anthropic 的 API，但你可以將其指向 Novita AI 的 Anthropic 相容端點，以使用成本效益高的開放權重模型 — 完全無需修改程式碼。

Novita AI 的端點鏡像了 Anthropic API 格式：

https://api.novita.ai/anthropic

在執行代理之前設定這兩個環境變數：

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"

你現有的 query() 呼叫無需修改即可運作。SDK 會自動讀取 ANTHROPIC_BASE_URL。

Novita AI 託管了一系列模型 — 包括 Kimi K2.5、GLM 5.2、MiniMax M2.1 和 Qwen 3.5 — 這些模型都可以透過此端點存取。對於構建執行數千個任務的代理管線的團隊來說，每個 token 的成本差異可能相當顯著。請參閱 Novita AI LLM API 以了解目前的模型目錄和定價。

如果你需要將代理部署到隔離的沙盒基礎設施中 — 這對於不希望代理觸碰主機檔案系統的自主程式碼執行非常有用 — Novita Agent Sandbox 提供了一個專為基於 Claude Agent SDK 的代理打造的 E2B 相容執行環境。

在 CI/CD 管線中使用 Claude Code SDK

SDK 的 permission_mode="acceptEdits" 和 allowed_tools 限制使其能夠在 CI 中無人值守地執行代理。典型的 GitHub Actions 模式：

- name: Run automated code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

其中 review_agent.py 包含類似以下內容：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

對於會寫回儲存庫的代理（自動重構、文件生成），請搭配一個 PostToolUse 鉤子，在變更到達 git 之前進行驗證。

故障排除

No matching distribution found for claude-agent-sdk 你的 Python 版本低於 3.10。執行 python3 --version 並根據需要升級。

ANTHROPIC_API_KEY is not set SDK 需要該環境變數。在執行前於你的 shell 或 .env 檔案中匯出它。

TypeScript 代理在完成前退出 確保你 await 了完整的迭代器循環。SDK 需要處理所有訊息事件後程序才會退出。

代理使用了意想不到的工具 使用 allowed_tools 明確限制工具集。如果你沒有指定，代理將可以存取所有內建工具。

子代理訊息未出現在輸出中 篩選 parent_tool_use_id 設定的訊息，以便將子代理輸出與主代理輸出區分開來。

會話恢復不正確 在第一次查詢開始時從 subtype === "init" 的 SystemMessage 中擷取 session_id，而不是從結果訊息中擷取。

常見問題

Claude Code SDK 和 Anthropic SDK 有什麼不同？

Claude Agent SDK（原名 Claude Code SDK）提供一個自主代理，自動處理工具執行。Anthropic Client SDK 提供原始 API 存取，你需要自行實作工具循環。對於代理管線請使用 Agent SDK；對於需要精確控制的直接模型呼叫請使用 Client SDK。

claude-agent-sdk 需要哪個 Python 版本？

Python 3.10 或更高版本。該套件無法安裝在 Python 3.9 或更舊版本上。

我需要安裝 Claude Code CLI 才能使用 TypeScript SDK 嗎？

不需要。@anthropic-ai/claude-agent-sdk 套件會將自己的原生 Claude Code 二進位檔案作為可選依賴項捆綁。

Claude Agent SDK 可以使用 Anthropic 的 Claude 以外的模型嗎？

透過將 ANTHROPIC_BASE_URL 設定為 Anthropic 相容端點，例如 https://api.novita.ai/anthropic，你可以使用該提供者託管的任何模型 — 包括來自 Kimi、GLM、MiniMax 或 Qwen 的開放權重模型。

Agent SDK 與 Claude Managed Agents 有什麼不同？

Managed Agents 是一個託管 REST API，Anthropic 在其基礎設施中運行代理。Agent SDK 是一個函式庫，可以在你自己的程序中、在你自己的檔案系統上運行代理循環。Agent SDK 更適合本地開發以及需要存取你的私有檔案或服務的代理。

Claude Agent SDK 支援串流輸出嗎？

query() 函數會返回一個非同步迭代器，當代理工作時會產生訊息。這提供了類似串流的行為 — 你可以在最終答案之前看到中間結果。

我可以將 Agent SDK 與 Amazon Bedrock 或 Vertex AI 一起使用嗎？

可以。設定 CLAUDE_CODE_USE_BEDROCK=1 加上 AWS 憑證給 Bedrock，或設定 CLAUDE_CODE_USE_VERTEX=1 加上 Google Cloud 憑證給 Vertex AI。

我應該先閱讀哪些 anthropic claude agent sdk 文件？

官方文件位於 code.claude.com/docs/en/agent-sdk/overview。從快速入門開始，然後在你有了一個可運作的代理後，再閱讀會話和鉤子指南。

推薦文章

• Claude Code CLI 文件：設定、Slash 指令與 LLM API 整合
• Vercel AI SDK：構建 AI 應用程式的完整開發者指南
• 如何使用 Novita Sandbox 部署和託管 Claude Agent SDK

---

資料來源檢查於 2026 年 7 月 3 日：Claude Agent SDK 文件、Novita AI LLM API