迁移到 Claude Agent SDK

概述

Claude Code SDK 已更名为 Claude Agent SDK，其文档也已重新组织。此更改反映了该 SDK 在构建 AI 代理方面更广泛的能力，不仅限于编码任务。

变更内容

迁移步骤

对于 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-opus-4-6"
)

# 之后
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. 查看破坏性变更

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

破坏性变更

Python：ClaudeCodeOptions 重命名为 ClaudeAgentOptions

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

迁移方法：

# 之前 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

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

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

options = ClaudeAgentOptions(
    model="claude-opus-4-6",
    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 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 以确保包已安装

后续步骤

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