迁移指南

Claude Code SDK 已更名为 Claude Agent SDK，反映其超越编码任务的更广泛能力。包名变更，同时有三处破坏性变更需要注意。

核心机制

包名变更：

语言	旧包名	新包名
TypeScript	`@anthropic-ai/claude-code`	`@anthropic-ai/claude-agent-sdk`
Python	`claude-code-sdk`	`claude-agent-sdk`
Python 导入	`from claude_code_sdk import ...`	`from claude_agent_sdk import ...`
Python 类型	`ClaudeCodeOptions`	`ClaudeAgentOptions`

三处破坏性变更：

TypeScript 迁移：

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

// 只需更新 import 路径，其他代码无需修改
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

Python 迁移：

pip uninstall claude-code-sdk
pip install claude-agent-sdk

# 更新导入和类型名
from claude_agent_sdk import query, ClaudeAgentOptions  # 原 ClaudeCodeOptions

恢复旧版系统提示行为：

# 旧版默认使用 claude_code preset，新版需显式设置
options = ClaudeAgentOptions(
    system_prompt={"type": "preset", "preset": "claude_code"}
)

隔离文件系统配置（CI/CD、多租户）：

options = ClaudeAgentOptions(setting_sources=[])  # 不加载任何文件系统配置

注意：Python SDK 0.1.59 及更早版本将空列表等同于省略（即加载所有来源），需升级后才能依赖 setting_sources=[] 的隔离效果。