Agent SDK移行ガイド — Claude Code SDKからの破壊的変更

Agent SDKへの移行で何が変わるか

Claude Code SDKは名称をClaude Agent SDKに変更し、ドキュメントも独立したAgent SDKセクションに再編されました。エージェント構築という役割がコーディング用途を超えて広がったための改称で、パッケージ名・import文・一部のオプション名が変わります。全面刷新ではなく、リネームに伴う3つの破壊的変更への対応が移行作業の中心です。

TypeScript/JavaScriptは @anthropic-ai/claude-code から @anthropic-ai/claude-agent-sdk へ。Pythonは claude-code-sdk から claude-agent-sdk へ。パッケージ自体が置き換わります。

旧パッケージ名は今どうなっているか

移行前に、レジストリ側の現状を押さえておくと判断を誤りません。

npmの @anthropic-ai/claude-code には現在も2.1.x系のバージョンが公開されています。一方で、レジストリに残る最古のバージョンは0.2.9で、移行ガイドの例にある "^0.0.42" は存在しません。^0.0.42 は0.0.42ちょうどだけを指す範囲なので、パッケージ名だけ変えてこの指定を残すと解決できる版がなく、インストールできません。

PyPIの claude-code-sdk は0.0.25が最後のリリースで、以降は更新されていません。移行先の claude-agent-sdk は0.1.0以降が破壊的変更を含む系列です。ただしレジストリには0.1.0より前のバージョンも残っており、最初のリリースはnpmが0.0.4、PyPIが0.0.23です。

バージョン範囲を決めるときは、0.1.0未満を指定するとシステムプロンプトの既定が旧挙動になる点に注意してください。破壊的変更の境目が0.1.0だと、移行ガイドが示しているためです。

新しい側にも前提があります。npmの @anthropic-ai/claude-agent-sdk 0.3.288は、peerDependenciesに zod(^4.0.0)・@anthropic-ai/sdk(>=0.93.0)・@modelcontextprotocol/sdk(^1.29.0)を要求します。Node.jsは18以上です。zodをv3系に固定しているプロジェクトは、入れ替えの前にこの範囲と合うかを確かめてください。

着手前のチェックは次の3点です。

• 現在のパッケージが @anthropic-ai/claude-code(TypeScript)または claude-code-sdk(Python)であること
• ClaudeCodeOptions を使ったコードがあるか(Pythonのみ該当)
• CI/CD・デプロイ済みアプリ・マルチテナント環境など、ファイルシステム上の設定を読み込ませたくない実行環境があるか

移行手順

TypeScript/JavaScriptプロジェクトの入れ替え

npm uninstall @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk

import文を書き換えます。

// Before
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
 
// After
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

package.json に @anthropic-ai/claude-code が残っていれば @anthropic-ai/claude-agent-sdk に置き換え、バージョン範囲も合わせて更新します(例: "^0.0.42" → "^0.3.0")。

Pythonプロジェクトの入れ替え

pip uninstall -y claude-code-sdk
pip install claude-agent-sdk

旧パッケージが入っていない環境では WARNING: Skipping claude-code-sdk as it is not installed. と出ますが、これは想定内の表示なのでそのまま次の手順に進んで問題ありません。requirements.txt や pyproject.toml に claude-code-sdk の記載があれば claude-agent-sdk に置き換えます。

import文も変わります。

# Before
from claude_code_sdk import query, ClaudeCodeOptions
 
# After
from claude_agent_sdk import query, ClaudeAgentOptions

旧パッケージの使用箇所を洗い出す

コードベースが大きいほど、旧パッケージへの参照は複数箇所に散らばります。入れ替えの前後で次の流れを踏むと、取りこぼしを防げます。

grep -rn "@anthropic-ai/claude-code" \
  --include="*.ts" --include="*.tsx" --include="*.json" .
grep -rn "claude_code_sdk\|ClaudeCodeOptions" --include="*.py" .

1本目は package.json の依存定義とimport文の両方を拾います。大きめのモノレポなら、移行完了までCIのlintルールに同じパターンを一時的に組み込み、旧名の再混入をプルリクエストで検知する方法もあります。anthropic パッケージ側のv1移行は/claude-api upgradeガイドが別の話題として扱っています。

破壊的変更への対応

ClaudeCodeOptionsのリネーム(Python)

Pythonの型 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")

TypeScript側にはこの型リネームはありません。

システムプロンプトが既定で使われなくなる

実運用への影響が最も大きい変更です。v0.0.x系ではオプションを何も指定しなくてもClaude Codeの既定システムプロンプトが使われていましたが、v0.1.0以降は最小限のシステムプロンプトが既定になりました。Claude Codeの振る舞いを前提にプロンプトを書いていたエージェントは、移行後に応答の傾向が変わって見えることがあります。

旧挙動が必要なら systemPrompt でpresetを明示指定します。

import { query } from "@anthropic-ai/claude-agent-sdk";
 
// AFTER (v0.1.0) - 既定は最小限のシステムプロンプト
// 旧挙動が必要ならpresetを明示指定する
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"
  }
});

Pythonでも同じ選択肢があります。

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio
 
 
async def main():
    # 旧挙動が必要ならpresetを明示指定する
    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)
 
 
asyncio.run(main())

判断の軸は2つです。Claude Codeの一般的な振る舞いを前提に組んだエージェントなら preset: "claude_code" を指定し、独自の役割を持たせたエージェントなら独自プロンプトを書きます。

移行直後は preset: "claude_code" を明示して旧挙動を固定し、そのうえで独自プロンプトへ段階的に移すと、変化の原因を切り分けられます。応答が変わったままエラーも出ない場合は、まずこの既定変更を疑います。SDK特有のエラーメッセージが出ているならAgent SDKのエラー集を引いてください。

この変更が及ぶのはSDK経由でエージェントを組んだコードだけです。Claude Code CLIを対話的に使う場合は従来どおり既定のシステムプロンプトで動くので、SDKとCLIを併用するチームは影響範囲を分けて共有しておくと混乱しません。

settingSourcesの既定動作は対応不要

settingSources の既定値はv0.1.0で一時的に変更された後、撤回されて元に戻っています。追加の移行作業は要りませんが、現在の挙動は押さえておく価値があります。

プロジェクト設定とフックは、cwd オプションで指定したディレクトリの .claude/ からだけ読み込まれ、親ディレクトリへのさかのぼりはありません。一方、CLAUDE.mdやSkillsは親ディレクトリも読み込み対象です。CIでリポジトリをチェックアウトして実行すると、コミット済みの .claude/settings.json は省略時に読み込まれます。SDKからSkillsやスラッシュコマンドを呼び出す方法はAgent SDK Skillsの使い方、プラグインを読み込む方法はAgent SDKプラグインをロードする方法にあります。

settingSources: [] でも読み込まれる入力があります。Agent SDKのドキュメントは、次の5種類を挙げています。

コネクタについては、mcpServers: {} を渡しても止まらない点に注意が必要です。claude.aiのログインで認証したセッションで読み込まれ、claude setup-token で作った CLAUDE_CODE_OAUTH_TOKEN では読み込まれません。

マルチテナントでは、既定の query() オプションだけを隔離の根拠にしないでください。ドキュメントは、テナントごとに別のファイルシステムで実行し、settingSources: [] と CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を併用する構成を示しています。

移行でつまずきやすい点

• バージョン範囲の更新漏れ: 旧パッケージ時代の指定が残ると、存在しない範囲を指して解決できなくなります
• peerDependenciesの不一致: zodなどが新しいSDKの要求範囲に入っているかを、入れ替え前に見ておきます
• ClaudeCodeOptions の取りこぼし: 呼び出し箇所の検索を、import元のリネーム後にもう一度回します
• CI環境での隔離漏れ: 分離が必要な実行環境では、settingSources に明示的に [] を渡します

移行後の動作確認には、Agent SDK入門で組む最小エージェントや、Agent SDKのサンプルと実例集のコードが使えます。パッケージ名とimportを置き換えるだけで動くものが大半です。

まとめ

作業の大半はパッケージとimportの置き換えで、動作に響くのはシステムプロンプトの既定変更です。応答の傾向が変わるかどうかを、旧挙動をpresetで固定した状態と比べて確かめれば、移行の影響範囲を絞れます。

CI/CDやマルチテナントで動かすなら、settingSources: [] で遮断できるのはファイルシステム上の設定だけです。ポリシー設定・Auto memory・MCPコネクタは別の手段で止めます。