Claude Code SDK から Agent SDK への移行手順と破壊的変更

Claude Code SDK は Claude Agent SDK に名前が変わり、ドキュメントも Agent SDK 専用の節に整理されました。コーディング以外にも使える、エージェント構築全般の SDK であることを表すための改名です。この記事では公式ドキュメント「Migrate to Claude Agent SDK」に沿って、TypeScript / JavaScript と Python それぞれの移行手順と、v0.1.0 で入った破壊的変更（オプション型の改名、システムプロンプトの既定、settingSources の扱い）を整理します。

何が変わったのか

公式ドキュメントが挙げる変更点は、パッケージ名とドキュメントの置き場所です。

移行の流れはどちらの言語でも同じで、「古いパッケージを外す → 新しいパッケージを入れる → import を書き換える → 破壊的変更を確認する」の4段階です。公式は、分離と明示的な設定を進めるために Claude Agent SDK v0.1.0 で破壊的変更が入ったと警告しています。パッケージ名を置き換えるだけでは挙動が変わる箇所があるので、後半の節まで確認してください。Agent SDK の全体像は「Claude Agent SDK でエージェントを作る」で扱っています。

TypeScript / JavaScript プロジェクトの移行

1. 古いパッケージをアンインストールします。

npm uninstall @anthropic-ai/claude-code

2. 新しいパッケージをインストールします。

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

3. import をすべて @anthropic-ai/claude-code から @anthropic-ai/claude-agent-sdk に書き換えます。query・tool・createSdkMcpServer などの名前はそのままです。

// 移行前
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 が残っていれば @anthropic-ai/claude-agent-sdk に置き換え、バージョン範囲も更新します。公式の例では "^0.0.42" を "^0.3.0" に変えています。旧パッケージの 0.0.x の範囲のまま新パッケージ名だけ変えると、意図したバージョンが入らないので注意します。

5. 最後に、後述の破壊的変更に合わせてコードを直します。

Python プロジェクトの移行

1. 古いパッケージをアンインストールします。

pip uninstall -y claude-code-sdk

旧パッケージが入っていない環境では WARNING: Skipping claude-code-sdk as it is not installed. と表示されますが、想定どおりの動作なのでそのまま次へ進んでかまいません。

2. 新しいパッケージをインストールします。requirements.txt や pyproject.toml に claude-code-sdk が書かれていれば claude-agent-sdk に置き換えます。PyPI のページでは、Python 3.10 以上が必要とされています。

pip install claude-agent-sdk

3. import をすべて claude_code_sdk から claude_agent_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")

引数の名前（model・permission_mode など）は変わらず、型名だけを置き換えれば動きます。PyPI のページの「Migrating from Claude Code SDK」でも、この ClaudeCodeOptions から ClaudeAgentOptions への改名が挙げられ、0.1.0 未満からの更新では CHANGELOG を確認するよう案内されています。

破壊的変更：システムプロンプトが既定でなくなった

v0.0.x の SDK は、何も指定しなければ Claude Code のシステムプロンプトを使っていました。v0.1.0 からは最小限のシステムプロンプトが既定になり、Claude Code のシステムプロンプトは自動では付きません。移行後に「以前と振る舞いが違う」と感じたら、まずここを確認します。

以前と同じ振る舞いにしたい場合は、systemPrompt に Claude Code のプリセットを明示します。独自のシステムプロンプトを文字列で渡すこともできます。

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

// 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"
  }
});

Python では ClaudeAgentOptions の system_prompt に同じ形の値を渡します。

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
    # Claude Code のプリセットを明示する
    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())

プリセットに指示を追記する方法など、システムプロンプトの細かい調整は「Agent SDK のシステムプロンプト変更」で扱っています。

settingSources の既定と分離の考え方

ファイルシステム上の設定を読むかどうか（settingSources）の既定値は、v0.1.0 で一時的に「何も読まない」に変わったあと、元に戻されました。そのため、この点について移行作業は不要です。

現在の挙動では、query() で settingSources を省略すると、CLI と同じくユーザー・プロジェクト・ローカルの設定を読み込みます。具体的には ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md ファイル、カスタムコマンドが対象です。

こうしたファイルシステム上の設定から切り離して動かしたい場合は、TypeScript では settingSources: []、Python では setting_sources=[] を渡します。

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

// ファイルシステム上の設定を読み込まずに実行する
for await (const message of query({
  prompt: "Hello",
  options: { settingSources: [] }
})) {
  console.log(message);
}

公式は、CI/CD パイプライン、デプロイしたアプリケーション、テスト環境、マルチテナントのシステムのように、手元のカスタマイズが紛れ込むと困る場面では特に分離が重要だとしています。なお Python SDK 0.1.59 以前は空のリストを「省略」と同じに扱っていたため、setting_sources=[] に頼る前に SDK を更新してください。また settingSources を [] にしても読まれる入力があります。各ソースが何を読むかは「Agent SDK で Claude Code 機能を使う」で整理しています。

本ページは Migrate to Claude Agent SDK を中心に、PyPI の claude-agent-sdk（インストール方法、Python 3.10 以上の要件、ClaudeCodeOptions から ClaudeAgentOptions への改名）を照合した非公式の日本語解説です（確認日 2026-11-03）。最新の仕様は公式ドキュメントを確認してください。