迁移到 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-sonnet-4-5"
)

# 之后
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. 查看 破坏性变更

进行任何必要的代码更改以完成迁移。

破坏性变更

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 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 集成