Claude Code SDK (Claude Agent SDK)：Python 和 TypeScript 指南

Claude Code SDK（在 Anthropic 的代理程式 SDK 版本中已更名為 Claude Agent SDK）是一個 Python 和 TypeScript 函式庫，用於在您的應用程式中執行自主編碼代理程式。它處理檔案讀取、指令、程式碼編輯、工具呼叫以及多步驟迭代，無需手動建置工具迴圈。透過 Novita AI 的 Anthropic 相容端點，同一個 SDK 也可以執行支援的開放權重模型，為團隊提供超越預設 Anthropic 後端的模型選擇和成本控制途徑。

本指南涵蓋開發人員入門所需的一切：安裝、核心 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);
}

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

步驟 5：使用工作階段恢復工作

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

若要恢復工作階段，請從 SystemMessage 初始化事件中擷取 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())

第二個提示使用了「那些相依性」— 這個引用之所以有意義，是因為工作階段攜帶了第一次呼叫的上下文。沒有 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())

在 allowed_tools 中包含 "Agent" 以預先批准子代理程式呼叫。來自子代理程式的訊息包含 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 規範的伺服器。位於 github.com/modelcontextprotocol/servers 的社群 MCP 註冊表列出了數百個整合，包括 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 提供了一個與 E2B 相容的執行環境，專為基於 Claude Agent SDK 建置的代理程式而設計。

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 的訊息，以將子代理程式輸出與主代理程式輸出區分開。

工作階段未正確恢復 從第一個查詢開始時的 SystemMessage（subtype === "init"）中擷取 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() 函式回傳一個非同步迭代器，會在代理程式工作時產生訊息。這提供了類似串流的行為 — 您可以在最終答案之前看到中間結果。

我可以在 Amazon Bedrock 或 Vertex AI 使用 Agent SDK 嗎？

可以。設定 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 文件：設定、斜線指令和 LLM API 整合
• Vercel AI SDK：建置 AI 應用程式的完整開發人員指南
• 如何使用 Novita Sandbox 部署和託管 Claude Agent SDK

---

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