文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

迁移到 Claude Agent SDK

将 Claude Code TypeScript 和 Python SDK 迁移到 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：

// 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.2.0"
  }
}

就是这样！不需要其他代码更改。

对于 Python 项目

1. 卸载旧包：

pip uninstall claude-code-sdk

2. 安装新包：

pip install 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. 更新类型名称：

将 ClaudeCodeOptions 更改为 ClaudeAgentOptions：

# Before
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7")

# After
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7")

5. 查看破坏性变更

进行完成迁移所需的任何代码更改。

破坏性变更

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")

变更原因： 类型名称现在与 "Claude Agent SDK" 品牌一致，并提供 SDK 命名约定的一致性。

系统提示不再默认使用

变更内容： SDK 不再默认使用 Claude Code 的系统提示。

迁移：

// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const result = 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 result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Or use a custom system prompt:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: "You are a helpful coding assistant"
  }
});

# 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:
from claude_agent_sdk import query, ClaudeAgentOptions

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)

变更原因： 为 SDK 应用程序提供更好的控制和隔离。您现在可以构建具有自定义行为的智能体，而无需继承 Claude Code 以 CLI 为中心的指令。

设置来源默认值

此默认值在 v0.1.0 中短暂更改过，然后被还原，因此无需迁移操作。

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

要运行与文件系统设置隔离的环境，请传递空数组：

const result = query({
  prompt: "Hello",
  options: {
    settingSources: [] // No filesystem settings loaded
  }
});

// Or load only specific sources:
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"] // Only project settings
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

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)

隔离对于 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 集成