本页目录10
- TypeScript/JS 包名由 @anthropic-ai/claude-code 改为 @anthropic-ai/claude-agent-sdk;Python 包名由 claude-code-sdk 改为 claude-agent-sdk
- Python 中 ClaudeCodeOptions 类型已重命名为 ClaudeAgentOptions，需同步修改所有引用
- v0.1.0 起 query() 默认不再使用 Claude Code 的系统提示词，需显式传入 systemPrompt: { type: "preset", preset: "claude_code" } 才能恢复旧行为
- 省略 settingSources 时仍会像 CLI 一样加载 user/project/local 三级文件系统设置；传入空数组 [] 可实现与文件系统隔离运行
- Python SDK 0.1.59 及更早版本会把空列表当作未设置处理，依赖 setting_sources=[] 前需先升级
- 隔离模式对 CI/CD、已部署应用、测试环境、多租户系统尤其重要，可避免本地自定义配置泄漏
本文是对官方 Agent SDK 某页的中文整理，完整与最新内容以原文为准：https://code.claude.com/docs/en/agent-sdk/migration-guide
概述
Claude Code SDK 已更名为 Claude Agent SDK，其文档也已重新组织。此变更反映了该 SDK 除编码任务之外，在构建 AI agent 方面更广泛的能力。
变更内容
| 方面 | 旧 | 新 |
|---|---|---|
| 包名（TS/JS） | @anthropic-ai/claude-code | @anthropic-ai/claude-agent-sdk |
| Python 包名 | claude-code-sdk | claude-agent-sdk |
| 文档位置 | Claude Code 文档 | Claude Code 文档 → 独立的 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:
// Before
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
// After
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.3.0"
}
}
5. 审阅破坏性变更
完成迁移所需的代码修改。
Python 项目
1. 卸载旧包：
pip uninstall -y claude-code-sdk
如果没有安装旧包，pip 会打印 WARNING: Skipping claude-code-sdk as it is not installed.，这是正常现象，可继续下一步。
2. 安装新包：
pip install claude-agent-sdk
如果 requirements.txt 或 pyproject.toml 中列出了 claude-code-sdk，将其替换为 claude-agent-sdk。
3. 更新导入语句：
将所有从 claude_code_sdk 的导入改为 claude_agent_sdk:
# Before
from claude_code_sdk import query, ClaudeCodeOptions
# After
from claude_agent_sdk import query, ClaudeAgentOptions
4. 审阅破坏性变更
完成迁移所需的代码修改。
破坏性变更
⚠️ 为提升隔离性与显式配置能力，Claude Agent SDK v0.1.0 针对从 Claude Code SDK 迁移的用户引入了破坏性变更。
Python:ClaudeCodeOptions 重命名为 ClaudeAgentOptions
变更内容： Python SDK 中的类型 ClaudeCodeOptions 已重命名为 ClaudeAgentOptions。
迁移方法：
# BEFORE (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
# AFTER (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
系统提示词不再默认启用
变更内容： SDK 默认不再使用 Claude Code 的系统提示词。
迁移方法：
TypeScript:
import { query } from "@anthropic-ai/claude-agent-sdk";
// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const before = query({ prompt: "Hello" });
// AFTER (v0.1.0) - Uses minimal system prompt by default
// To get the old behavior, explicitly request Claude Code's preset:
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// Or use a custom system prompt:
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
Python:
from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio
async def main():
# BEFORE (v0.0.x) - Used Claude Code's system prompt by default
async for message in query(prompt="Hello"):
print(message)
# AFTER (v0.1.0) - Uses minimal system prompt by default
# To get the old behavior, explicitly request Claude Code's preset:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset
),
):
print(message)
# Or use a custom system prompt:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)
asyncio.run(main())
为什么这样改： 为 SDK 应用提供更好的控制和隔离能力。现在你可以构建具有自定义行为的 agent，而不会继承 Claude Code 面向 CLI 场景的默认指令。
settingSources 的默认行为
此默认行为曾在 v0.1.0 中短暂改为「不加载任何文件系统设置」，随后又被还原，因此无需为此进行迁移操作。
当前行为： 在 query() 中省略 settingSources 时，会像 CLI 一样加载 user、project、local 三级文件系统设置，包括 ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md 文件以及自定义命令。
若要与文件系统设置隔离运行，可传入空数组：
TypeScript:
import { query } from "@anthropic-ai/claude-agent-sdk";
const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // No filesystem settings loaded
}
});
// Or load only specific sources:
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Only project settings
}
});
Python:
from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]), # No filesystem settings loaded
):
print(message)
# Or load only specific sources:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"] # Only project settings
),
):
print(message)
asyncio.run(main())
隔离模式对 CI/CD 流水线、已部署的应用、测试环境以及多租户系统尤为重要——在这些场景下，本地自定义配置不应该被意外带入运行环境。
注意： Python SDK 0.1.59 及更早版本会把空列表当作与「省略该选项」相同处理，因此在依赖
setting_sources=[]之前请先升级版本。关于即便settingSources为[]时仍会被读取的输入，参见 What settingSources does not control。
后续步骤
- 阅读 Agent SDK Overview 了解可用功能
- 查阅 TypeScript SDK Reference 获取详细 API 文档
- 查阅 Python SDK Reference 获取 Python 专属文档
- 了解 Custom Tools 与 MCP Integration