古法编程

Appearance

Claude Code SDK 已更名为 Claude Agent SDK，包名和导入路径均需更新。旧用户只需卸载旧包、安装新包并修改所有导入语句即可，TypeScript 和 Python 升级步骤类似。注意新版不再默认使用 Claude Code 系统提示，需手动指定 systemPrompt: { type: "preset", preset: "claude_code" } 恢复旧行为；设置来源默认加载文件系统配置，隔离环境需传入空数组。迁移后验证 npm install 或 pip install 成功即可。

Claude Code SDK 怎么迁移到 Claude Agent SDK ​

概述 ​

Claude Code SDK 已更名为 Claude Agent SDK，文档结构也随之调整。这次改名反映了 SDK 更广泛的能力——不再局限于编程任务，而是构建通用 AI Agent。

变更内容 ​

方面旧版新版
包名 (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Python 包名claude-code-sdkclaude-agent-sdk
文档位置Claude Code 文档API Guide → Agent SDK 章节

文档调整后的位置： Agent SDK 文档已从 Claude Code 文档移至 API Guide 下的独立 Agent SDK 部分。Claude Code 文档现在专注于 CLI 工具和自动化功能。

迁移步骤 ​

TypeScript/JavaScript 项目 ​

1. 卸载旧包

bash
npm uninstall @anthropic-ai/claude-code

2. 安装新包

bash
npm install @anthropic-ai/claude-agent-sdk

3. 更新 import 语句

将所有 @anthropic-ai/claude-code 改为 @anthropic-ai/claude-agent-sdk：

typescript
// 迁移前
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// 迁移后
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. 更新 package.json 依赖

如果 package.json 中直接引用旧包，改成新包：

json
// 迁移前
{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

// 迁移后
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}

完成以上步骤即可，无需其他代码改动。

Python 项目 ​

1. 卸载旧包

bash
pip uninstall claude-code-sdk

2. 安装新包

bash
pip install claude-agent-sdk

3. 更新 import 语句

将所有 claude_code_sdk 改为 claude_agent_sdk：

python
# 迁移前
from claude_code_sdk import query, ClaudeCodeOptions

# 迁移后
from claude_agent_sdk import query, ClaudeAgentOptions

4. 更新类型名

将 ClaudeCodeOptions 改为 ClaudeAgentOptions：

python
# 迁移前
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. 处理 Breaking changes

根据下面的破坏性变更说明调整代码。

Breaking changes ​

Claude Agent SDK v0.1.0 引入了破坏性变更，主要目的是增强隔离性和显式配置。迁移前请仔细阅读本部分。

Python: ClaudeCodeOptions 改名为 ClaudeAgentOptions ​

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

迁移方法：

python
# 迁移前 (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 的系统提示。

迁移方法：

typescript
// 迁移前 (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"
  }
});
python
# 迁移前 (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 应用提供更好的控制和隔离性。你可以构建自定义行为的 Agent，而不会继承 Claude Code 的 CLI 指令。

设置来源的默认行为 ​

该默认值在 v0.1.0 中短暂更改后又恢复，因此无需迁移操作。

当前行为： 省略 settingSources 的 query() 会加载用户、项目和本地文件系统设置，与 CLI 一致。包括 ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md 文件和自定义命令。

要隔离文件系统设置，传入空数组：

typescript
const result = query({
  prompt: "Hello",
  options: {
    settingSources: [] // 不加载文件系统设置
  }
});

// 或者只加载特定来源：
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"] // 仅项目设置
  }
});
python
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 流水线、部署的应用、测试环境以及多租户系统尤为重要——避免本地定制项泄露。

SDK v0.1.0 曾短暂默认不加载设置，后续版本已回滚。Python SDK 0.1.59 及更早版本将空数组视为省略选项，因此升级后才能依赖 setting_sources=[]。关于即使 settingSources 为 [] 时也会读取的输入，请参见 settingSources 不控制的内容。

为什么改名？ ​

Claude Code SDK 最初为编程任务设计，但它已发展成构建各种 AI Agent 的强大框架。新名称 "Claude Agent SDK" 更准确地反映其能力：

  • 构建业务 Agent（法律助手、财务顾问、客服）
  • 创建专业编码 Agent（SRE 机器人、安全审查员、代码审查 Agent）
  • 开发任意领域的自定义 Agent，支持工具使用、MCP 集成等

获取帮助 ​

迁移中遇到问题：

TypeScript/JavaScript：

  1. 检查所有 import 是否已更新为 @anthropic-ai/claude-agent-sdk
  2. 确认 package.json 中包名已更换
  3. 执行 npm install 确保依赖更新

Python：

  1. 检查所有 import 是否已更新为 claude_agent_sdk
  2. 确认 requirements.txt 或 pyproject.toml 中包名已更换
  3. 执行 pip install claude-agent-sdk 确保安装成功

下一步 ​

常见问题 ​

迁移后运行代码报错 "Cannot find module '@anthropic-ai/claude-code'" ​

还没卸载旧包或没安装新包。先执行 npm uninstall @anthropic-ai/claude-code 然后 npm install @anthropic-ai/claude-agent-sdk，并更新所有 import 语句。

为什么升级后我的 Agent 行为完全变了，不再按 CLi 模式运行 ​

因为新版不再默认使用 Claude Code 系统提示。在 Options 中显式设置 systemPrompt: { type: "preset", preset: "claude_code" }（TypeScript）或 system_prompt={"type": "preset", "preset": "claude_code"}（Python）即可恢复旧行为。

我传了 setting_sources=[] 但它还是加载了本地配置文件怎么办 ​

检查 Claude Agent SDK 的 Python 版本是否 >= 0.2.0。Python SDK 0.1.59 及更早版本中空数组被忽略，必须升级后才能隔离设置。另外，某些输入（如环境变量中指定的 CLAUDE.md 路径）即使 settingSources 为空也会被读取，详见 settingSources 不控制的内容。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策