遷移至 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 部分 |
遷移步驟
針對 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": "^0.0.42"
}
}
之後：
{
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.0"
}
}
5. 檢查重大變更
進行完成遷移所需的任何代碼變更。
針對 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_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7")
# 之後
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7")
5. 檢查重大變更
進行完成遷移所需的任何代碼變更。
重大變更
Python：ClaudeCodeOptions 重新命名為 ClaudeAgentOptions
變更內容： Python SDK 類型 ClaudeCodeOptions 已重新命名為 ClaudeAgentOptions。
遷移：
# 之前 (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
# 之後 (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 的系統提示。
遷移：
import { query } from "@anthropic-ai/claude-agent-sdk";
// 之前 (v0.0.x) - 預設使用 Claude Code 的系統提示
const before = query({ prompt: "Hello" });
// 之後 (v0.1.0) - 預設使用最小系統提示
// 要獲得舊行為，明確請求 Claude Code 的預設值：
const presetResult = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// 或使用自訂系統提示：
const customResult = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
# 之前 (v0.0.x) - 預設使用 Claude Code 的系統提示
async for message in query(prompt="Hello"):
print(message)
# 之後 (v0.1.0) - 預設使用最小系統提示
# 要獲得舊行為，明確請求 Claude Code 的預設值：
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"} # 使用預設值
),
):
print(message)
# 或使用自訂系統提示：
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 檔案和自訂命令。
要從檔案系統設定中隔離運行，請傳遞空陣列：
import { query } from "@anthropic-ai/claude-agent-sdk";
const isolatedResult = query({
prompt: "Hello",
options: {
settingSources: [] // 未載入檔案系統設定
}
});
// 或僅載入特定來源：
const projectOnlyResult = query({
prompt: "Hello",
options: {
settingSources: ["project"] // 僅專案設定
}
});
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]), # 未載入檔案系統設定
):
print(message)
# 或僅載入特定來源：
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"] # 僅專案設定
),
):
print(message)
隔離對於 CI/CD 管道、已部署的應用程式、測試環境和多租戶系統特別重要，其中本地自訂不應洩露。
為什麼重新命名？
Claude Code SDK 最初是為編碼任務設計的，但它已發展成為構建所有類型 AI 代理的強大框架。新名稱「Claude Agent SDK」更好地反映了其功能：
- 構建業務代理（法律助手、財務顧問、客戶支援）
- 建立專門的編碼代理（SRE 機器人、安全審查員、代碼審查代理）
- 為任何領域開發自訂代理，具有工具使用、MCP 整合等功能
獲取幫助
如果您在遷移過程中遇到任何問題：
針對 TypeScript/JavaScript：
- 檢查所有匯入是否已更新為使用
@anthropic-ai/claude-agent-sdk - 驗證您的 package.json 具有新套件名稱
- 執行
npm install以確保依賴項已更新
針對 Python：
- 檢查所有匯入是否已更新為使用
claude_agent_sdk - 驗證您的 requirements.txt 或 pyproject.toml 具有新套件名稱
- 執行
pip install claude-agent-sdk以確保套件已安裝
後續步驟
- 探索 Agent SDK 概述 以了解可用功能
- 查看 TypeScript SDK 參考 以取得詳細的 API 文檔
- 檢查 Python SDK 參考 以取得 Python 特定文檔
- 了解 自訂工具 和 MCP 整合