跳轉到主要內容

​
概述

Claude Code SDK 已重新命名為 Claude Agent SDK，其文檔已重新組織。此變更反映了 SDK 在構建 AI 代理方面的更廣泛功能，超越了僅編碼任務。

​
變更內容

方面舊版本新版本
套件名稱 (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Python 套件claude-code-sdkclaude-agent-sdk
文檔位置Claude Code 文檔 → SDK 部分API 指南 → Agent SDK 部分
文檔變更： Agent SDK 文檔已從 Claude Code 文檔移至 API 指南下的專用 Agent SDK 部分。Claude Code 文檔現在專注於 CLI 工具和自動化功能。

​
遷移步驟

​
針對 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-sonnet-4-5"
)

# 之後
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"
)
5. 檢閱 重大變更 進行完成遷移所需的任何代碼變更。

​
重大變更

為了改進隔離和明確配置，Claude Agent SDK v0.1.0 為從 Claude Code SDK 遷移的用戶引入了重大變更。在遷移前請仔細檢閱本部分。

​
Python：ClaudeCodeOptions 重新命名為 ClaudeAgentOptions

變更內容： Python SDK 類型 ClaudeCodeOptions 已重新命名為 ClaudeAgentOptions。 遷移： 
# 之前 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)

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

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    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.md 指令等），請在選項中新增 settingSources: ['user', 'project', 'local']。

​
為什麼重新命名？

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 以確保套件已安裝
請參閱 疑難排解 指南以了解常見問題。

​
後續步驟