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() 返回响应对象
内置工具	读取、写入、编辑、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	对现有文件进行针对性编辑
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 已设置的消息，将子智能体输出与主智能体输出区分开来。

会话未正确恢复 在第一次查询开始时从 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 或更早版本上安装。

使用 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 文档：设置、Slash 命令和 LLM API 集成
• Vercel AI SDK：构建 AI 应用的完整开发者指南
• 如何使用 Novita Sandbox 部署和托管 Claude Agent SDK

---

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