跳转到主要内容

​
概述

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

​
变更内容

方面旧版本新版本
包名称 (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Python 包claude-code-sdkclaude-agent-sdk
文档位置Claude Code 文档 → SDK 部分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": "^1.0.0"
  }
}

// 之后
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.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_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5"
)

# 之后
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"
)
5. 查看 破坏性变更 进行完成迁移所需的任何代码更改。

​
破坏性变更

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

​
Python：ClaudeCodeOptions 重命名为 ClaudeAgentOptions

变更内容： Python SDK 类型 ClaudeCodeOptions 已重命名为 ClaudeAgentOptions。 迁移： 
# 之前 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)

# 之后 (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)
为什么变更： 类型名称现在与”Claude Agent SDK”品牌相匹配，并在 SDK 的命名约定中提供一致性。

​
系统提示不再默认使用

变更内容： SDK 不再默认使用 Claude Code 的系统提示。 迁移： 
// 之前 (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"
  }
});
为什么变更： 为 SDK 应用程序提供更好的控制和隔离。现在可以构建具有自定义行为的代理，而无需继承 Claude Code 的 CLI 专注指令。

​
设置源不再默认加载

变更内容： SDK 不再默认从文件系统设置（CLAUDE.md、settings.json、斜杠命令等）读取。 迁移： 
// 之前 (v0.0.x) - 自动加载所有设置
const result = query({ prompt: "Hello" });
// 会读取：
// - ~/.claude/settings.json (用户)
// - .claude/settings.json (项目)
// - .claude/settings.local.json (本地)
// - CLAUDE.md 文件
// - 自定义斜杠命令

// 之后 (v0.1.0) - 默认不加载设置
// 要获得旧行为：
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

// 或仅加载特定源：
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"]  // 仅项目设置
  }
});
为什么变更： 确保 SDK 应用程序具有独立于本地文件系统配置的可预测行为。这对以下情况特别重要：
  • CI/CD 环境 - 无本地自定义的一致行为
  • 已部署的应用程序 - 不依赖文件系统设置
  • 测试 - 隔离的测试环境
  • 多租户系统 - 防止用户之间的设置泄露
向后兼容性： 如果应用程序依赖文件系统设置（自定义斜杠命令、CLAUDE.md 指令等），请将 settingSources: ['user', 'project', 'local'] 添加到选项中。

​
为什么重命名？

Claude Code SDK 最初是为编码任务设计的，但它已发展成为构建所有类型 AI 代理的强大框架。新名称”Claude Agent SDK”更好地反映了其功能：
  • 构建业务代理（法律助手、财务顾问、客户支持）
  • 创建专门的编码代理（SRE 机器人、安全审查员、代码审查代理）
  • 使用工具使用、MCP 集成等为任何领域开发自定义代理

​
获取帮助

如果在迁移过程中遇到任何问题： 对于 TypeScript/JavaScript：
  1. 检查所有导入是否已更新为使用 @anthropic-ai/claude-agent-sdk
  2. 验证 package.json 是否具有新的包名称
  3. 运行 npm install 以确保依赖项已更新
对于 Python：
  1. 检查所有导入是否已更新为使用 claude_agent_sdk
  2. 验证 requirements.txt 或 pyproject.toml 是否具有新的包名称
  3. 运行 pip install claude-agent-sdk 以确保包已安装
有关常见问题，请参阅 故障排除 指南。

​
后续步骤