背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

公式ドキュメント：https://code.claude.com/docs/ja/agent-sdk/migration-guide

1. 一言でいうと

以前「Claude Code SDK」という名前で提供されていた SDK は、「Claude Agent SDK」に名前が変わりました。コーディング以外も含めた AI エージェント全般を作るための SDK だ、ということを名前に反映したものです。移行の作業は、パッケージを入れ替えて import を書き換えることと、v0.1.0 で入った「破壊的変更」に合わせてコードを直すことの2つです。とくに、既定のシステムプロンプトが Claude Code のものではなくなった変更は、エラーにならずに振る舞いだけが変わるので注意が要ります。

第76回の SDK の概要で、改名があり移行ガイドがあることに触れました。今回はその本体です。連載の Agent SDK の回はすべて新しい名前（@anthropic-ai/claude-agent-sdk、claude-agent-sdk）を前提に書いてきたので、古いコードを持っている人がそこにたどり着くための回でもあります。

---

2. どういう場面で役立つか

シーン1：古い名前の SDK で書いたアプリを動かし続けたい

@anthropic-ai/claude-code や claude-code-sdk を使って書いたアプリを、今の SDK に載せ替える場面です。パッケージ名、import、Python のオプションの型名を変えれば、まず動くようになります。

シーン2：載せ替えたら、エージェントの振る舞いが変わった

エラーは出ないのに、エージェントの答え方やツールの使い方が以前と違う、という場面です。原因の筆頭は、既定のシステムプロンプトの変更です（3-4）。

シーン3：設定ファイルから切り離して動かしているつもりのアプリを点検する

CI、本番のアプリ、テスト環境、マルチテナントのシステムで、settingSources: [] によってローカルの設定から切り離しているはずのアプリです。古い Python SDK では、この指定が効いていませんでした（3-5）。

不要・向かないケース

• 最初から claude-agent-sdk で書いている：移行の作業はありません。ただし 3-5 の Python の古い版の注意は、版を上げていないなら当てはまります。
• OpenAI Agents SDK から移りたい：このページの対象外です。原文は別に「OpenAI Agents SDK 移行レシピ」を案内しており、1つの実装例を通じて各部品を Claude Agent SDK に対応づけているとしています。

---

3. コードと仕組みの解説

原文の fenced コードブロックは9本です（TypeScript の移行手順3本、Python の移行手順3本、Python のオプション名の変更1本、システムプロンプトの変更の TypeScript と Python の対訳1組）。手順のページなので全数を引用します。コードは原文から機械的に抜き出したもので、入れ子に由来する先頭インデントを外した以外は変えていません。

3-0. バージョンに関わる事実

項目	内容
破壊的変更が入った版	Claude Agent SDK v0.1.0
TypeScript の package.json のバージョン範囲の例	"^0.0.42" から "^0.3.0" へ
setting_sources=[] が正しく効かなかった版	Python SDK 0.1.59 以前（空のリストを省略と同じに扱っていた）

3行目は、移行と関係なく現在のアプリにも関わる重大な注意です。詳しくは 3-5 で見ます。

3-1. 何が変わったか

項目	旧	新
パッケージ名（TS/JS）	@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
Python のパッケージ	claude-code-sdk	claude-agent-sdk
ドキュメントの場所	Claude Code のドキュメント	Claude Code のドキュメントの中の、専用の Agent SDK の節

名前の変更は、原文によれば「コーディングのタスクだけでなく、AI エージェントを作るための SDK の、より広い機能を反映した」ものです。

3-2. TypeScript／JavaScript のプロジェクトを移行する

手順は5つです。

1. 古いパッケージを外す

npm uninstall @anthropic-ai/claude-code

2. 新しいパッケージを入れる

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

3. import を書き換える

@anthropic-ai/claude-code からの import をすべて @anthropic-ai/claude-agent-sdk に変えます。

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

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

import する名前（query、tool、createSdkMcpServer）は変わらず、モジュールの名前だけが変わります。tool と createSdkMcpServer は第83回の自作ツールで使った関数です。

4. package.json を更新する

package.json に @anthropic-ai/claude-code が残っていれば @anthropic-ai/claude-agent-sdk に置き換え、バージョンの範囲も更新します。原文の例は "^0.0.42" から "^0.3.0" です。

5. 破壊的変更を確認する（3-4・3-5）

3-3. Python のプロジェクトを移行する

手順は4つです。

1. 古いパッケージを外す

pip uninstall -y claude-code-sdk

古いパッケージが入っていなければ、pip は WARNING: Skipping claude-code-sdk as it is not installed. と出します。これは想定どおりの動きなので、そのまま次に進みます。

2. 新しいパッケージを入れる

pip install claude-agent-sdk

requirements.txt や pyproject.toml に claude-code-sdk が書かれていれば、claude-agent-sdk に置き換えます。

3. import を書き換える

claude_code_sdk からの import をすべて claude_agent_sdk に変えます。

# Before
from claude_code_sdk import query, ClaudeCodeOptions

# After
from claude_agent_sdk import query, ClaudeAgentOptions

TypeScript と違い、Python は import する型の名前も変わります（ClaudeCodeOptions → ClaudeAgentOptions）。モジュール名だけを一括置換すると、ClaudeCodeOptions が見つからないというエラーになります。

4. 破壊的変更を確認する（3-4・3-5）

	TypeScript	Python
パッケージの入れ替え	npm uninstall → npm install	pip uninstall -y → pip install
依存の記述の更新	package.json（バージョン範囲も）	requirements.txt／pyproject.toml
import の変更	モジュール名だけ	モジュール名と、オプションの型名

表は筆者の整理です。

3-4. 破壊的変更

原文は警告として、Claude Agent SDK v0.1.0 は、分離と明示的な設定を改善するために、Claude Code SDK から移るユーザー向けの破壊的変更を入れたと書いています。

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

引数（model、permission_mode）はそのままで、型の名前と import 元だけが変わっています。

(b) システムプロンプトが既定ではなくなった

SDK は既定では Claude Code のシステムプロンプトを使わなくなりました。 v0.0.x では既定で Claude Code のシステムプロンプトを使っていましたが、v0.1.0 からは既定で最小限のシステムプロンプトを使います。以前の振る舞いにしたいなら、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"
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
    # BEFORE (v0.0.x) - デフォルトで Claude Code のシステムプロンプトを使用していました
    async for message in query(prompt="Hello"):
        print(message)

    # AFTER (v0.1.0) - デフォルトで最小限のシステムプロンプトを使用します
    # 以前の動作を取得するには、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())

指定の仕方は、TypeScript が systemPrompt: { type: "preset", preset: "claude_code" }、Python が system_prompt={"type": "preset", "preset": "claude_code"} です。独自のものは文字列をそのまま渡します。なお Python の例は、「BEFORE」の部分も新しい claude_agent_sdk から import していますが、これはコメントにあるとおり v0.0.x での振る舞いを示すためのもので、同じコードを今の SDK で動かすと最小限のプロンプトになります（筆者の解釈）。

筆者の指摘：この変更は、移行で最も気づきにくいものです。パッケージと import を直せばコードはエラーなく動きますが、システムプロンプトは黙って最小限のものに変わります。第86回で見たとおり、最小限の既定には、Claude Code のプリセットにある安全上の指示や、作業ディレクトリ・環境の情報が入っていません。古い SDK で「Claude Code と同じように」動いていたコーディングの自動化をそのまま移すなら、claude_code のプリセットを明示するのが、以前の振る舞いに近づける確実な方法です。逆に、コーディング以外のエージェントなら、これを機に自分のシステムプロンプトを書くのがよいでしょう（第86回の選び方）。

3-5. 設定ソースの既定

このデフォルトはv0.1.0 で一時的に「ファイルシステムの設定を読み込まない」に変えられ、その後元に戻されたので、原文は移行の作業は要らないとしています。

今の振る舞い：query() で settingSources を省略すると、ユーザー・プロジェクト・ローカルのファイルシステムの設定が読み込まれ、CLI と同じになります。対象は ~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、CLAUDE.md、カスタムコマンドなどです（第100回の表）。

ファイルシステムの設定から切り離して動かすには、settingSources: []（Python は setting_sources=[]）を渡します。原文は、この分離がローカルの設定が漏れてはいけない CI/CD のパイプライン、デプロイしたアプリ、テスト環境、マルチテナントのシステムで特に重要だとしています。

そして原文の注記が、このページで最も重い一文です。Python SDK 0.1.59 以前は、空のリストを省略と同じに扱っていたので、setting_sources=[] に頼る前に版を上げる必要があります。つまり古い Python SDK では、setting_sources=[] と書いても、ユーザー・プロジェクト・ローカルの設定がすべて読み込まれていたことになります。また、[] にしても読み込まれる入力（管理ポリシー、~/.claude.json、自動メモリなど）があることは、第100回のとおりです。

筆者の指摘は2つです。

1. 第94回・第100回のマルチテナント分離の手順は、Python では 0.1.59 より後の版が前提ということになります。古い版のまま setting_sources=[] で分離したつもりのアプリは、ホストのユーザー設定やプロジェクトのフック・権限ルールを読み込んでいた可能性があります。今動いているアプリの Python SDK の版を確かめる価値があります。
2. v0.1.0 の一時的な既定（読み込まない）の時期に書かれたコードは、逆向きの影響を受けえます。その時期に「settingSources を省略すればファイルの設定は読まれない」前提で書いたコードは、今の SDK では CLI と同じく全部を読み込みます。原文は「移行の作業は要らない」としていますが、分離が必要なアプリなら、省略に頼らず [] を明示するのが確実です。

---

4. まとめ

• Claude Code SDK は Claude Agent SDK に改名。TS は @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk、Python は claude-code-sdk → claude-agent-sdk。
• TS は uninstall → install → import のモジュール名を変更 → package.json（例：^0.0.42 → ^0.3.0）→ 破壊的変更の確認。
• Python は uninstall（入っていなければ警告が出るが問題なし）→ install → requirements.txt／pyproject.toml → import を変更（型名も ClaudeCodeOptions → ClaudeAgentOptions）→ 破壊的変更の確認。
• v0.1.0 の破壊的変更：Python のオプション型名の変更と、既定のシステムプロンプトが Claude Code のものから最小限のものに。エラーにならずに振る舞いが変わるので、以前と同じにしたいなら claude_code プリセットを明示する。
• 設定ソースの既定は v0.1.0 で一時的に変わって元に戻ったので、今は省略で CLI と同じく全部読む。分離したいなら []。
• Python SDK 0.1.59 以前は setting_sources=[] が省略と同じ扱い。分離に頼る前に版を上げる。[] でも読み込まれる入力もある。

次回予告

次回は 「TypeScript SDK リファレンス」（agent-sdk/typescript） を取り上げる予定です。

これまでの Agent SDK の回では、SDKSystemMessage の plugin_errors、startup() や prewarm()、ツール出力の型 TaskCreateOutput など、詳しい定義を「TypeScript リファレンスを参照」として先送りしてきました。今回の移行ガイドも、次に読むものとして TypeScript と Python のリファレンスを挙げています。次回は、TypeScript SDK の関数・オプション・メッセージの型がどう整理されているのかを、これまでの回とのつながりを中心に見ていきます。

---