你是否在升級Claude SDK時遇到配置不兼容、工具調用失敗等問題？本文將系統梳理從舊版到GitHub_Trending/cl/claude-code-sdk-python的遷移要點，通過10個核心步驟+5個代碼示例，幫你2小時內完成無痛遷移，同時掌握新特性帶來的性能提升。

遷移準備與環境檢查

遷移前請確保滿足以下環境要求，避免版本不兼容導致的常見問題：

  • Python 3.10+（舊版最低支持3.8，src/claude_agent_sdk/client.py中已明確標註版本檢查邏輯）
  • Claude Code 2.0.0+：npm install -g @anthropic-ai/claude-code（README.md）
  • 移除舊版SDK：pip uninstall claude-code-sdk

推薦使用虛擬環境隔離依賴：

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install claude-agent-sdk

核心API變更速覽

變更類型

舊版實現

新版實現

影響範圍

核心類重命名

ClaudeCodeOptions

ClaudeAgentOptions

所有配置代碼

系統提示配置

custom_system_prompt + append_system_prompt

統一為system_prompt字段

初始化配置

MCP服務器接入

僅支持外部進程

新增in-process SDK服務器

工具集成模塊

會話管理

無顯式控制

fork_session參數支持會話分支

多輪對話場景

完整變更日誌參見CHANGELOG.md，建議重點關注v0.1.0版本的"Breaking Changes"章節

配置體系遷移

1. 初始化參數調整

最顯著的變化是配置類重命名，需全局替換所有引用：

# 舊版
from claude_code_sdk import ClaudeCodeOptions
options = ClaudeCodeOptions(allowed_tools=["Bash"])

# 新版 [src/claude_agent_sdk/types.py](https://link.gitcode.com/i/5190ab393e101e5090258bbe889cda3d)
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(allowed_tools=["Bash"])

2. 系統提示配置重構

系統提示配置從分散的兩個參數合併為統一的system_prompt字段，支持預設模板與自定義文本：

# 舊版
options = ClaudeCodeOptions(
    custom_system_prompt="You are a calculator",
    append_system_prompt=True
)

# 新版 [README.md#basic-usage-query](https://link.gitcode.com/i/a66a3ef8dc10201b46db00bc9e20e063)
options = ClaudeAgentOptions(
    # 使用預設模板
    system_prompt={"type": "preset", "preset": "claude_code"},
    # 或自定義文本
    # system_prompt="You are a calculator that only returns JSON"
)

3. 設置源控制

新版默認不再加載文件系統配置（如settings.json），需顯式指定：

# 僅加載項目級設置
options = ClaudeAgentOptions(
    setting_sources=["project"]  # 可選值: "user", "project", "local"
)

工具系統升級

MCP服務器遷移：從外部進程到In-Process

新版SDK引入的SDK MCP服務器徹底改變了工具集成方式，將工具調用延遲從平均200ms降至20ms以下。以下是計算器工具的遷移示例：

# 舊版：外部進程MCP服務器
options = ClaudeCodeOptions(
    mcp_servers={
        "calculator": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "calculator_server"]
        }
    }
)

# 新版：In-Process SDK服務器 [examples/mcp_calculator.py](https://link.gitcode.com/i/020dee3c3ffcad644473ed7a97a1d1ce)
from claude_agent_sdk import create_sdk_mcp_server, tool

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add_numbers(args):
    return {"content": [{"type": "text", "text": f"{args['a'] + args['b']}"}]}

calculator = create_sdk_mcp_server(
    name="calc",
    tools=[add_numbers]
)

options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add"]  # 工具ID格式變更
)

工具ID命名規則變為：mcp__{server_name}__{tool_name}，需更新所有工具權限配置

工具調用流程優化

新版ClaudeSDKClient支持雙向流對話，工具調用更流暢：

# 新版工具調用流程 [examples/streaming_mode.py](https://link.gitcode.com/i/406f1287c80e27b4a56a1ae17401d972)
async with ClaudeSDKClient(options=options) as client:
    await client.query("Calculate 25 * 4 + 18")
    
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, ToolUseBlock):
                    print(f"工具調用: {block.name}, 參數: {block.input}")

錯誤處理增強

新版定義了更精細的錯誤類型體系，建議更新異常處理邏輯：

# 新版錯誤處理 [src/claude_agent_sdk/_errors.py](https://link.gitcode.com/i/e5900739ee913d0767141fc2d41b6f7d)
from claude_agent_sdk import (
    CLINotFoundError,    # Claude Code未安裝
    CLIConnectionError,  # 連接失敗
    ProcessError         # 進程執行錯誤
)

try:
    async for msg in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("請安裝最新版Claude Code: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"進程錯誤: 退出碼{e.exit_code}, 詳情:{e.stderr}")

高級特性遷移

會話分支管理

新版支持會話分支功能，可在同一對話基礎上探索不同路徑：

# 會話分支示例 [CHANGELOG.md#new-features](https://link.gitcode.com/i/791818ce3249e509ed911d09a7a8eab1)
async with ClaudeSDKClient(options=options) as client:
    # 初始對話
    await client.query("生成一個Python排序算法")
    base_session = client.session_id  # 保存會話ID
    
    # 創建分支會話
    await client.query("修改為降序排列", fork_session=base_session)

鈎子系統應用

新版鈎子系統可攔截工具調用，實現自動化審批流程：

# 鈎子示例 [examples/hooks.py](https://link.gitcode.com/i/8efb82b32fb2acaa803b5a7093a131d9)
async def check_bash_safety(input_data, tool_use_id, context):
    if input_data["tool_name"] == "Bash" and "rm -rf" in input_data["tool_input"]["command"]:
        return {
            "hookSpecificOutput": {
                "permissionDecision": "deny",
                "permissionDecisionReason": "禁止危險命令"
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [HookMatcher(matcher="Bash", hooks=[check_bash_safety])]
    }
)

遷移驗證清單

完成代碼修改後，建議通過以下步驟驗證遷移效果：

  1. 運行基礎示例：python examples/quick_start.py（examples/quick_start.py）
  2. 執行工具測試：python examples/mcp_calculator.py驗證MCP服務器功能
  3. 檢查錯誤處理：故意傳入無效參數，確認異常捕獲正常
  4. 性能對比：使用相同prompt對比新舊版響應時間（新版應提升30%+）

完整測試套件參見e2e-tests/目錄，包含工具權限、鈎子系統等專項測試

常見問題解決

Q: 遷移後工具調用提示"permission denied"？

A: 檢查allowed_tools配置，新版工具ID格式為mcp__{server_name}__{tool_name}，需同步更新權限列表。

Q: 系統提示不生效？

A: 確認使用新版system_prompt參數，且未設置衝突的setting_sources。可通過print(options.system_prompt)調試配置值。

Q: 升級後出現依賴衝突？

A: 執行pip show claude-agent-sdk確認版本，確保無舊版殘留。推薦創建全新虛擬環境測試。

遷移總結與新特性展望

本次遷移不僅是API調整，更是架構升級：從單一代碼助手進化為全功能AI Agent開發框架。重點掌握：

  • 配置中心化：ClaudeAgentOptions提供統一配置入口
  • 工具本地化：In-Process MCP服務器大幅提升性能
  • 會話可控化：fork_session支持實驗性對話分支

即將發佈的v0.2.0版本將新增多模態輸入和插件系統，建議關注CHANGELOG.md獲取更新通知。遷移過程中遇到任何問題，可提交issue至項目倉庫或參考examples/目錄下的完整示例。