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 へ。パッケージ自体が置き換わります。新パッケージへの移行が公式に案内されているため、旧パッケージのまま放置せず計画的に移行することをおすすめします。

移行前に確認する前提

移行はコード変更よりもパッケージの入れ替えが主です。着手前に次を確認してください。

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

3点目は見落とされがちです。ローカル設定が意図せず混入する環境かどうかで、移行後に追加対応が要るか決まります。

移行手順

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")。パッケージ名だけ変えてバージョン指定を放置すると、存在しないバージョン範囲を指定したままになり npm install が解決に失敗します。

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

3つの破壊的変更

パッケージとimportを揃えたら、次の3点をコードに反映します。

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())

移行の判断基準はシンプルです。Claude Codeの一般的な振る舞いを前提に組んだエージェントならpreset: "claude_code"を指定し、独自の役割を持たせたエージェントならそのまま独自プロンプトを書きます。何も指定しない場合との違いを把握しないまま移行すると、応答品質の変化に気づくのが本番投入後になりかねません。

この変更が及ぶのはSDK経由でエージェントを組んでいるコードだけで、Claude Code CLI本体を対話的に使う場合の挙動には影響しません。CLIは従来通りClaude Codeの既定システムプロンプトで動きます。混同しやすいポイントなので、SDKとCLIを併用しているチームは影響範囲を分けて説明しておくと社内の混乱を防げます。

settingSourcesの既定動作は対応不要

settingSources の既定値はv0.1.0で一時的に変更された後、撤回されて元に戻っています。そのため追加の移行作業は不要です。ただし現在の挙動を正しく理解しておく価値はあります。

query() で settingSources を省略すると、CLIと同じくユーザー・プロジェクト・ローカルのファイルシステム設定を読み込みます。対象は ~/.claude/settings.json / .claude/settings.json / .claude/settings.local.json / CLAUDE.mdファイル群 / .claude/ 配下のSkills・サブエージェント・カスタムコマンドです。SDKからSkillsやスラッシュコマンドを呼び出す具体的な方法はAgent SDK Skillsの使い方で扱っています。同様に .claude/plugins/ 配下のプラグインもこの設定ソースの制御対象で、SDKでのロード方法はAgent SDKプラグインをロードする方法にまとめています。CI/CDパイプライン・デプロイ済みアプリ・テスト環境・マルチテナントシステムのように、ローカルのカスタマイズを持ち込みたくない実行環境では settingSources: [](Pythonは setting_sources=[])を渡してファイルシステムから切り離します。

settingSources: [] を渡しても及ばない範囲があることも押さえておく必要があります。管理者が設定したポリシー設定と、グローバルな ~/.claude.json の設定は、このオプションの値にかかわらず常に読み込まれます。加えてAuto memoryとclaude.aiのMCPコネクタも settingSources: [] の対象外です。マルチテナント環境でAuto memoryまで遮断したい場合は環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 を別途設定する必要があります。「完全に隔離した」と思い込んで組織のポリシー設定・Auto memory・MCPコネクタを見落とすと、想定と違うツール権限やモデル設定、あるいは意図しない記憶の持ち込みが適用されたまま気づかないことになります。マルチテナント環境を運用するなら、settingSources: [] はファイルシステム上のプロジェクト/ユーザー設定を遮断するものであって、組織のポリシー層・Auto memory・MCPコネクタまで遮断するものではないと理解しておいてください。

既存コードベースで旧パッケージの使用箇所を洗い出す

チームで運用しているコードベースが大きいほど、旧パッケージへの参照が複数箇所に散らばっている可能性があります。パッケージの入れ替えに着手する前に、次のコマンドで参照箇所を洗い出しておくと取りこぼしを防げます。

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

TypeScript側の1本目は package.json の依存関係定義とimport文の両方を拾います。ヒットしたファイルごとにimportとバージョン範囲を書き換え、最後にもう一度同じコマンドを実行してヒット数が0件になったことを確認してください。Python側の2本目はパッケージ名と型名の両方を1回で検出できるので、ClaudeCodeOptions を別名で再エクスポートして回避するような中途半端な対応をしていないかもここで見つけられます。

大きめのモノレポでは、CIのlintルールに同じパターンを一時的に組み込み、移行完了までのプルリクエストで旧パッケージ名の再混入を検知する運用も有効です。移行が完了したらルールごと削除して構いません。

移行でつまずきやすい4点

• バージョン範囲の更新漏れ: パッケージ名だけ変えてバージョン指定を旧パッケージ時代のまま残すと、存在しない範囲を指定した状態で解決エラーになります
• ClaudeCodeOptions の呼び出し箇所の取りこぼし: 型エイリアスとして再エクスポートして回避するのではなく、実際のimport元をリネームしてから全呼び出し箇所を検索するほうが確実です
• システムプロンプトの変化を検知しないままの本番投入: 移行直後は preset: "claude_code" を明示して旧挙動を固定し、必要に応じて独自プロンプトへ段階的に移行するほうが影響を切り分けやすくなります
• CI環境での設定漏れ込み: settingSources を省略したままCI/CD環境で実行すると、開発者個人の ~/.claude/settings.json がCIには存在しなくても、リポジトリの .claude/settings.local.json が意図せず読み込まれる場合があります。分離が必要な環境では明示的に [] を渡してください

移行作業自体はAgent SDK入門で組んだ最小エージェントのコードにも同じ手順が適用できます。パッケージ名とimportを置き換えるだけで動くケースが大半です。

よくある質問

npm/pipどちらを先に更新すべきか

順序に技術的な制約はありません。TypeScriptプロジェクトならnpm、Pythonプロジェクトならpipの手順だけを実施すれば十分です。両方の言語でSDKを併用している場合は、どちらから始めても他方に影響しません。

ClaudeCodeOptions未使用でも対応は要るか

Pythonで型を直接参照していなければ、パッケージ名とimport元の書き換えだけで完了します。TypeScriptにはこの型自体が存在しないため、システムプロンプトと settingSources の挙動確認だけを行ってください。

移行後にエージェントの応答が変わった場合はどうするか

まずシステムプロンプトの既定変更が原因かどうかを切り分けます。systemPrompt: { type: "preset", preset: "claude_code" } を明示して旧挙動に戻し、応答が安定するなら原因はここです。それでも解消しない場合は、Agent SDK特有のエラーメッセージが出ていないかAgent SDKのエラー集で確認してください。

移行を試すサンプルコードはあるか

公式の実践的なサンプルはAgent SDKのサンプルと実例集にまとめています。移行後のパッケージで動くか確認する足がかりとして使えます。

まとめ

Claude Agent SDKへの移行は、パッケージ名とimportの置き換え、Pythonの ClaudeAgentOptions へのリネーム、システムプロンプトの既定変更への対応という3点に集約されます。settingSources の既定動作は撤回済みで追加対応は不要ですが、CI/CDやマルチテナント環境を運用しているチームは分離設定の要否を今回のタイミングで見直す価値があります。旧パッケージ(@anthropic-ai/claude-code / claude-code-sdk)から新パッケージへの移行は公式に案内されているため、新規プロジェクトはもちろん、稼働中のエージェントも計画的に移行してください。