SpyBara
Go Premium

agent-sdk/migration-guide.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 50 additions and 150 deletions.

2026
Thu 10 23:00

遷移至 Claude Agent SDK

將 Claude Code TypeScript 和 Python SDK 遷移至 Claude Agent SDK 的指南

概述

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

從 OpenAI Agents SDK 遷移？OpenAI Agents SDK 遷移配方透過單一實作範例將每個原始元素對應到 Claude Agent SDK。

有什麼改變

方面 舊版 新版
套件名稱 (TS/JS) @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
Python 套件 claude-code-sdk claude-agent-sdk
文件位置 Claude Code 文件 Claude Code 文件 → 專用的 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：

如果 @anthropic-ai/claude-code 仍列在您的 package.json 中，請將其替換為 @anthropic-ai/claude-agent-sdk 並同時更新版本範圍，例如從 "^0.0.42" 更新為 "^0.3.0"。

5. 檢閱重大變更

進行任何必要的程式碼變更以完成遷移。

針對 Python 專案

1. 解除安裝舊套件：

pip uninstall -y claude-code-sdk

如果舊套件未安裝，pip 會列印 WARNING: Skipping claude-code-sdk as it is not installed. 這是預期的行為，您可以繼續進行下一步。

2. 安裝新套件：

pip install claude-agent-sdk

如果 claude-code-sdk 列在您的 requirements.txt 或 pyproject.toml 中，請將其替換為 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. 檢閱重大變更

進行任何必要的程式碼變更以完成遷移。

破壞性變更

Python：ClaudeCodeOptions 重新命名為 ClaudeAgentOptions

變更內容： Python SDK 類型 ClaudeCodeOptions 已重新命名為 ClaudeAgentOptions。

遷移：

# 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")

系統提示詞不再為預設值

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

遷移：

import { query } from "@anthropic-ai/claude-agent-sdk";

// BEFORE (v0.0.x) - 預設使用 Claude Code 的系統提示詞
const before = query({ prompt: "Hello" });

// AFTER (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.1.0 中曾短暫變更為不載入任何檔案系統設定，隨後已還原，因此不需要進行遷移操作。

目前行為： 在 query() 上省略 settingSources 會載入使用者、專案和本機檔案系統設定，與 CLI 相符。這包括 ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md 檔案和自訂命令。

若要隔離檔案系統設定執行，請傳遞 settingSources: []，或在 Python 中傳遞 setting_sources=[]。請參閱使用 settingSources 控制檔案系統設定以了解每個來源載入的內容。

隔離對於 CI/CD 管道、已部署的應用程式、測試環境和多租戶系統特別重要，其中本機自訂設定不應洩漏。

後續步驟