迁移到 Claude Agent SDK
将 Claude Code TypeScript 和 Python SDK 迁移到 Claude Agent SDK 的指南
概述
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 部分 |
迁移步骤
对于 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"
}
}
5. 查看 破坏性变更
进行完成迁移所需的任何代码更改。
对于 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. 查看 破坏性变更
进行完成迁移所需的任何代码更改。
破坏性变更
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 的系统提示。
迁移：
import { query } from "@anthropic-ai/claude-agent-sdk";
// 之前 (v0.0.x) - 默认使用 Claude Code 的系统提示
const before = query({ prompt: "Hello" });
// 之后 (v0.1.0) - 默认使用最小系统提示
// 要获得旧行为，请显式请求 Claude Code 的预设：
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// 或使用自定义系统提示：
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
# 之前 (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 文件和自定义命令。
要从文件系统设置中隔离运行，请传递空数组：
import { query } from "@anthropic-ai/claude-agent-sdk";
const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // 未加载文件系统设置
}
});
// 或仅加载特定源：
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // 仅项目设置
}
});
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 管道、已部署的应用程序、测试环境和多租户系统特别重要，其中本地自定义不应泄露。
为什么重命名？
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 集成