{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：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 智能体方面的更广泛能力。

## 变更内容

| 方面                       | 旧名称                        | 新名称                             |
| :------------------------- | :---------------------------- | :--------------------------------- |
| **包名（TS/JS）**          | `@anthropic-ai/claude-code`   | `@anthropic-ai/claude-agent-sdk`   |
| **Python 包**              | `claude-code-sdk`             | `claude-agent-sdk`                 |
| **文档位置**               | Claude Code 文档              | API 指南 → Agent SDK 部分          |

<Note>
  **文档变更：** Agent SDK 文档已从 Claude Code 文档移至 API 指南下的专用 [Agent SDK](/en/agent-sdk/overview) 部分。Claude Code 文档现在专注于 CLI 工具和自动化功能。
</Note>

## 迁移步骤

### 对于 TypeScript/JavaScript 项目

**1. 卸载旧包：**

```bash theme={null}
npm uninstall @anthropic-ai/claude-code
```

**2. 安装新包：**

```bash theme={null}
npm install @anthropic-ai/claude-agent-sdk
```

**3. 更新导入：**

将所有导入从 `@anthropic-ai/claude-code` 更改为 `@anthropic-ai/claude-agent-sdk`：

```typescript theme={null}
// 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` 中列出了该包，请更新它：

之前：

```json theme={null}
{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}
```

之后：

```json theme={null}
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}
```

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

### 对于 Python 项目

**1. 卸载旧包：**

```bash theme={null}
pip uninstall claude-code-sdk
```

**2. 安装新包：**

```bash theme={null}
pip install claude-agent-sdk
```

**3. 更新导入：**

将所有导入从 `claude_code_sdk` 更改为 `claude_agent_sdk`：

```python theme={null}
# Before
from claude_code_sdk import query, ClaudeCodeOptions

# After
from claude_agent_sdk import query, ClaudeAgentOptions
```

**4. 更新类型名称：**

将 `ClaudeCodeOptions` 更改为 `ClaudeAgentOptions`：

```python theme={null}
# 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. 查看[破坏性变更](#breaking-changes)**

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

## 破坏性变更

<Warning>
  为了改善隔离性和显式配置，Claude Agent SDK v0.1.0 为从 Claude Code SDK 迁移的用户引入了破坏性变更。迁移前请仔细查看本节。
</Warning>

### Python：ClaudeCodeOptions 重命名为 ClaudeAgentOptions

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

**迁移：**

```python theme={null}
# 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 的系统提示。

**迁移：**

<CodeGroup>
  ```typescript TypeScript theme={null}
  // 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"
    }
  });
  ```

  ```python Python theme={null}
  # 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)
  ```
</CodeGroup>

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

### 设置来源默认值

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

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

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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
    }
  });
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

隔离对于 CI/CD 管道、部署的应用程序、测试环境和多租户系统尤其重要，本地自定义不应泄漏到这些系统中。

<Note>
  SDK v0.1.0 短暂默认为不加载设置；这在后续版本中被还原。Python SDK 0.1.59 及更早版本将空列表视为与省略选项相同，因此在依赖 `setting_sources=[]` 之前请升级。有关即使 `settingSources` 为 `[]` 也会读取的输入，请参阅 [settingSources 不控制的内容](/en/agent-sdk/claude-code-features#what-settingsources-does-not-control)。
</Note>

## 为什么更名？

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 概述](/en/agent-sdk/overview)以了解可用功能
* 查看 [TypeScript SDK 参考](/en/agent-sdk/typescript)以获取详细的 API 文档
* 查看 [Python SDK 参考](/en/agent-sdk/python)以获取 Python 特定的文档
* 了解[自定义工具](/en/agent-sdk/custom-tools)和 [MCP 集成](/en/agent-sdk/mcp)