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 字段的消息）——代理的最终响应
• SystemMessage（subtype === "init"）——包含用于后续恢复的 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 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())

第二个提示使用了“那些依赖”——这个引用之所以有意义，正是因为会话携带了第一次调用的上下文。如果没有 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 规范的服务器。社区 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 或更早版本上。

使用 TypeScript SDK 是否需要安装 Claude Code CLI？

不需要。@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 文档：搭建、斜杠命令及 LLM API 集成
• Vercel AI SDK：构建 AI 应用的完整开发者指南
• 如何使用 Novita Sandbox 部署和托管 Claude Agent SDK

---

来源检查于 2026 年 7 月 3 日：Claude Agent SDK 文档、Novita AI LLM API