遷移至 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：

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

// 之後
import {
  query,
  tool,
  createSdkMcpServer,
} from "@anthropic-ai/claude-agent-sdk";

4. 更新 package.json 依賴項：

如果您的 package.json 中列有該套件，請更新它：

// 之前
{
  "dependencies": {
    "@anthropic-ai/claude-code": "^1.0.0"
  }
}

// 之後
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
  }
}

就這樣！不需要其他程式碼變更。

針對 Python 專案

1. 解除安裝舊套件：

pip uninstall claude-code-sdk

2. 安裝新套件：

pip install claude-agent-sdk

3. 更新您的匯入：

將所有從 claude_code_sdk 的匯入更改為 claude_agent_sdk：

# 之前
from claude_code_sdk import query, ClaudeCodeOptions

# 之後
from claude_agent_sdk import query, ClaudeAgentOptions

4. 更新型別名稱：

將 ClaudeCodeOptions 更改為 ClaudeAgentOptions：

# 之前
from claude_agent_sdk import query, ClaudeCodeOptions

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

# 之後
from claude_agent_sdk import query, ClaudeAgentOptions

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

5. 檢閱重大變更

進行完成遷移所需的任何程式碼變更。

重大變更

Python：ClaudeCodeOptions 更名為 ClaudeAgentOptions

變更內容： Python SDK 型別 ClaudeCodeOptions 已更名為 ClaudeAgentOptions。

遷移方式：

# 之前 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-opus-4-6",
    permission_mode="acceptEdits"
)

# 之後 (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-opus-4-6",
    permission_mode="acceptEdits"
)

變更原因： 型別名稱現在與「Claude Agent SDK」品牌一致，並在 SDK 的命名慣例中提供一致性。

系統提示詞不再為預設值

變更內容： SDK 不再預設使用 Claude Code 的系統提示詞。

遷移方式：

// 之前 (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"
  }
});

變更原因： 為 SDK 應用程式提供更好的控制和隔離性。您現在可以建構具有自訂行為的代理，而不會繼承 Claude Code 以 CLI 為導向的指令。

設定來源不再預設載入

變更內容： SDK 不再預設從檔案系統設定（CLAUDE.md、settings.json、斜線命令等）讀取。

遷移方式：

// 之前 (v0.0.x) - 自動載入所有設定
const result = query({ prompt: "Hello" });
// 會讀取自：
// - ~/.claude/settings.json（使用者）
// - .claude/settings.json（專案）
// - .claude/settings.local.json（本地）
// - CLAUDE.md 檔案
// - 自訂斜線命令

// 之後 (v0.1.0) - 預設不載入任何設定
// 若要恢復舊行為：
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

// 或僅載入特定來源：
const result = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"]  // 僅專案設定
  }
});

變更原因： 確保 SDK 應用程式具有可預測的行為，不受本地檔案系統配置影響。這對以下情況尤其重要：

• 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 整合