Claude Code官方文档Agent SDK迁移

Claude Agent SDK 迁移指南 - 从 Claude Code SDK 迁移

将 Claude Code TypeScript 和 Python SDK 迁移到 Claude Agent SDK 的指南。

发布于 2025年5月1日 · 阅读约 11 分钟

概述

Claude Code SDK 已重命名为 Claude Agent SDK，其文档已重新组织。这一变化反映了该 SDK 在构建超越编码任务的 AI 代理方面的更广泛功能。

变更内容

方面	旧版本	新版本
包名称 (TS/JS)	`@anthropic-ai/claude-code`	`@anthropic-ai/claude-agent-sdk`
Python 包	`claude-code-sdk`	`claude-agent-sdk`
文档位置	Claude Code 文档	API 指南 → Agent SDK 部分

ℹ️ 文档变更： Agent SDK 文档已从 Claude Code 文档移至 API 指南下的专门 Agent SDK 部分。Claude Code 文档现在专注于 CLI 工具和自动化功能。

迁移步骤

对于 TypeScript/JavaScript 项目

1. 卸载旧包：

npm uninstall @anthropic-ai/claude-code

2. 安装新包：

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

3. 更新导入：

将所有导入从 @anthropic-ai/claude-code 更改为 @anthropic-ai/claude-agent-sdk：

// 之前
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// 之后
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. 更新 package.json 依赖项：

如果您在 package.json 中列出了该包，请更新它：

之前：

{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

之后：

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}

就这样！无需进行其他代码更改。

对于 Python 项目

1. 卸载旧包：

pip uninstall claude-code-sdk

2. 安装新包：

pip install claude-agent-sdk

3. 更新导入：

将所有导入从 claude_code_sdk 更改为 claude_agent_sdk：

# 之前
from claude_code_sdk import query, ClaudeCodeOptions

# 之后
from claude_agent_sdk import query, ClaudeAgentOptions

4. 更新类型名称：

将 ClaudeCodeOptions 更改为 ClaudeAgentOptions：

# 之前
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7")

# 之后
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7")

5. 查看破坏性变更

进行完成迁移所需的任何代码更改。

破坏性变更

⚠️ 为了改进隔离和显式配置，Claude Agent SDK v0.1.0 为从 Claude Code SDK 迁移的用户引入了破坏性变更。在迁移前请仔细查看本部分。

Python：ClaudeCodeOptions 重命名为 ClaudeAgentOptions

变更内容： Python SDK 类型 ClaudeCodeOptions 已重命名为 ClaudeAgentOptions。

迁移：

# 之前 (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# 之后 (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

为什么变更： 类型名称现在与”Claude Agent SDK”品牌相匹配，并在 SDK 的命名约定中提供一致性。

系统提示不再是默认值

变更内容： SDK 不再默认使用 Claude Code 的系统提示。

迁移：

TypeScript

// 之前 (v0.0.x) - 默认使用 Claude Code 的系统提示
const result = query({ prompt: "Hello" });

// 之后 (v0.1.0) - 默认使用最小系统提示
// 要获得旧行为，请显式请求 Claude Code 的预设：
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// 或使用自定义系统提示：
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: "You are a helpful coding assistant"
  }
});

Python

# 之前 (v0.0.x) - 默认使用 Claude Code 的系统提示
async for message in query(prompt="Hello"):
    print(message)

# 之后 (v0.1.0) - 默认使用最小系统提示
# 要获得旧行为，请显式请求 Claude Code 的预设：
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}  # 使用预设
    ),
):
    print(message)

# 或使用自定义系统提示：
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
    print(message)

为什么变更： 为 SDK 应用程序提供更好的控制和隔离。您现在可以构建具有自定义行为的代理，而无需继承 Claude Code 的 CLI 焦点指令。

设置源默认值

此默认值在 v0.1.0 中曾短暂更改，然后被还原，因此无需迁移操作。

当前行为： 在 query() 上省略 settingSources 会加载用户、项目和本地文件系统设置，与 CLI 匹配。这包括 ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md 文件和自定义命令。

要从文件系统设置中隔离运行，请传递空数组：

TypeScript

const result = query({
  prompt: "Hello",
  options: {
    settingSources: [] // 未加载文件系统设置
  }
});

// 或仅加载特定源：
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"] // 仅项目设置
  }
});

Python

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(setting_sources=[]),  # 未加载文件系统设置
):
    print(message)

# 或仅加载特定源：
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        setting_sources=["project"]  # 仅项目设置
    ),
):
    print(message)

隔离对于 CI/CD 管道、已部署的应用程序、测试环境和多租户系统特别重要，其中本地自定义不应泄露。

ℹ️ SDK v0.1.0 曾短暂默认为不加载任何设置；这在后续版本中被还原。Python SDK 0.1.59 及更早版本将空列表视为与省略选项相同，因此在依赖 setting_sources=[] 之前请升级。有关即使 settingSources 为 [] 时仍会读取的输入，请参阅 settingSources 不控制的内容。

为什么重命名？

Claude Code SDK 最初是为编码任务设计的，但它已发展成为构建所有类型 AI 代理的强大框架。新名称”Claude Agent SDK”更好地反映了其功能：

构建业务代理（法律助手、财务顾问、客户支持）
创建专门的编码代理（SRE 机器人、安全审查员、代码审查代理）
为任何领域开发自定义代理，具有工具使用、MCP 集成等功能

获取帮助

如果您在迁移过程中遇到任何问题：

对于 TypeScript/JavaScript：

检查所有导入是否已更新为使用 @anthropic-ai/claude-agent-sdk
验证您的 package.json 具有新的包名称
运行 npm install 以确保依赖项已更新

对于 Python：

检查所有导入是否已更新为使用 claude_agent_sdk
验证您的 requirements.txt 或 pyproject.toml 具有新的包名称
运行 pip install claude-agent-sdk 以确保包已安装

后续步骤

探索 Agent SDK 概述以了解可用功能
查看 TypeScript SDK 参考以获取详细的 API 文档
查看 Python SDK 参考以获取 Python 特定文档
了解自定义工具和 MCP 集成

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。