2026 年 6 月のリネーム後に起きる claude-code-sdk のインポートエラー：原因と直し方

アップグレード直後にビルドが ModuleNotFoundError: No module named 'claude_code_sdk' で壊れたり、@anthropic-ai/claude-code には query という export メンバーがないと TypeScript に言われたりしても、あなたが何か間違えたわけではありません。パッケージが移動したのです。

ややこしいのは、npm install @anthropic-ai/claude-code はいまも成功する点です。ただし、いまは別物がインストールされます。あなたが覚えている名前は CLI ツールを指していて、SDK は荷物をまとめて出ていきました。

2026 年 6 月、Anthropic は Claude Code SDK を Claude Agent SDK にリネームしました。TypeScript パッケージは @anthropic-ai/claude-agent-sdk に、Python パッケージは claude-agent-sdk になりました。古い名前のすべてがきれいに 404 になったわけではなく、それがエラーを紛らわしくしている当の理由です。これは書き直しではなく、ピンポイントの修正です。何が壊れて、なぜで、両言語の正確な before/after を以下に示します。

30 秒の修正：Before → After

リネームが触るのはパッケージ名、インポートパス、そして（Python では）1 つのクラス名です。古い行を新しい行に対応づければ、ほとんどのコードはそのまま動きます。

執筆時点の現行バージョン：@anthropic-ai/claude-agent-sdk は 0.3.x、PyPI の claude-agent-sdk は 0.2.x です。凍結された古いパッケージは claude-code-sdk 0.0.25（Python）に留まり、@anthropic-ai/claude-code はいまや CLI の 2.1.x です。より深い理由を知りたいなら、この記事の残りで各エラー文字列を一つずつ追います。

なぜインポートが壊れたか（CLI と SDK の名前衝突）

手短に言うと、SDK は @anthropic-ai/claude-code から出ていきましたが、そのパッケージ名は CLI ツールとして生き残ったため、インストールは成功し、インポートは失敗します。この食い違いがこの移行で最大の混乱源なので、いまどの名前を誰が持っているのかを正確にしておく価値があります。

2026 年 6 月より前、@anthropic-ai/claude-code は 2 つのものを同梱していました：claude CLI バイナリと、プログラマブルな SDK（query、tool、createSdkMcpServer）です。リネーム後、この 2 つの役割は分かれました。

つまり npm install @anthropic-ai/claude-code は失敗しません。CLI がインストールされます。すると import { query } from "@anthropic-ai/claude-code" が失敗します。そのパッケージはもう SDK のシンボルを export しないからです。エラーメッセージはインポートを指しますが、本当の問題はインストールしたパッケージです。

リネーム自体はスコープを反映しています。SDK はコーディング補助として始まり、エージェント（サポートボット、レビューエージェント、金融アシスタント）を構築する汎用フレームワークへ成長しました。だから「Code SDK」より「Agent SDK」の方が実態を表します。これを使ってエージェントを組むのが初めてなら、Python AI エージェント開発ガイド が、この SDK の上に載るループとツール配線のパターンを扱っています。

エラーメッセージ → 修正表

下の各エラー文字列は、1 つの根本原因に対応します：古い名前を指しているのです。自分の正確なメッセージを見つけて、対応する修正を当ててください。

TypeScript / JavaScript の修正

古いパッケージをアンインストールし、新しいものをインストールし、インポート文字列を書き換えます。シンボル名（query、tool、createSdkMcpServer）は変わっていないので、ほとんどのファイルではインポートだけが唯一の編集です。

npm uninstall @anthropic-ai/claude-code
npm install @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";

package.json で依存をピン留めしていたなら、キーも更新してください。古いエントリを残すと、両方のパッケージがインストールされたまま、エディタが間違った方から query を解決するという混乱に陥ります。

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.3.0"
  }
}

grep する価値のある落とし穴が 1 つ。スクリプトでも CLI（claude コマンド）を使うなら、その用途には @anthropic-ai/claude-code をインストールしたままにしてよいですが、そこから SDK シンボルをインポートしてはいけません。CLI と SDK は、2 つの別々の仕事を持つ 2 つの別々の依存として扱ってください。

Python の修正

claude-code-sdk をアンインストールし、claude-agent-sdk をインストールし、インポートモジュールとオプションクラス名を変えます。コンストラクタの引数は同じなので、model、permission_mode などはそのまま引き継がれます。

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

インポートとクラスを書き換えます。

# Before
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# After
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

最初の失敗の陰に 2 つ目が隠れています：claude-agent-sdk には Python 3.10 以降が必要です。3.9 で venv を作ると、pip はインストールを拒否するか何もインストールしないため、「インストールした」のに ModuleNotFoundError: No module named 'claude_agent_sdk' が出ます。インポートが実際に走るインタプリタを確認してください。

python -c "import sys; print(sys.version)"
python -c "import claude_agent_sdk; print(claude_agent_sdk.__file__)"

1 つ目が 3.9.x を出すなら、3.10+ で venv を作り直します。2 つ目が例外を吐くのに pip show claude-agent-sdk には載っているなら、スクリプトを動かしている環境とは別の環境にインストールしたということです。これが SDK の issue トラッカーで「インストールしたのに見つからない」報告の最もよくある原因です。

誰も読まない破壊的変更：デフォルトのシステムプロンプト

デフォルトのシステムプロンプトは v0.1.0 以降でなくなりました。そのためインポートがコンパイルを通った後でも、エージェントの挙動は変わります。これはビルドは直るのに挙動を静かに変える唯一の変更なので、移行が終わったように見えてから 1 週間後に人を噛みます。

古い SDK バージョンは Claude Code の CLI 向けシステムプロンプトを自動で注入していました。v0.1.0 から SDK は最小限のデフォルトを同梱します。以前の挙動に戻すには、プリセットにオプトインします。

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

// Restore the old Claude Code behavior:
const result = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

# Restore the old Claude Code behavior:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        system_prompt={"type": "preset", "preset": "claude_code"}
    ),
):
    print(message)

あるいはプレーンな文字列を渡して（TS では systemPrompt: "You are a helpful coding assistant"、Python では system_prompt="..."）独自のものを定義できます。デプロイ済みエージェントにはこちらの方が良いデフォルトです。CLI 風の指示がサポートボットに漏れ込むのは普通望まないからです。エージェントがツール定義に依存しているなら、プロンプトの変更でツールの選ばれ方が変わることがあります。ファンクションコーリングとツール利用ガイド が、システムプロンプトとツールスキーマがどう作用し合うかを扱っています。

ガイドからもう 1 つの細かい点：settingSources は v0.1.0 で一時的に「何も読み込まない」がデフォルトになり、その後差し戻されました。いまは省略するとユーザー、プロジェクト、ローカルのファイルシステム設定を読み込み、CLI に揃います。隔離された実行には settingSources: []（TS）または setting_sources=[]（Python）を渡してください。これは CI やマルチテナントのデプロイで効きます。Python SDK 0.1.59 以前は空リストをオプション省略と同じに扱っていたので、これに頼る前にアップグレードしてください。

この修正が効かないとき（とその代わり）

エラーがモジュールの欠落、export の欠落、リネームされたクラスなら、リネーム修正を当ててください。症状が次のいずれかなら、別の修正に飛んでください。

• まだ Python 3.9 でアップグレードできない。 リネームは関係ありません。SDK がインストールされません。インタプリタをアップグレードするか、古い claude-code-sdk 0.0.25 をピン留めし、修正が来ないことを受け入れてください。
• 認証またはネットワークエラー（401、ECONNRESET、タイムアウト）。 それはランタイムの問題で、インポートではありません。パッケージ名は正しいので、代わりに認証情報、base URL、リトライを見てください。Claude Code を安全に動かす のメモが、権限と設定の罠をいくつか扱っています。
• 移行後のコスト急増。 リネームは無料ですが、トークン使用量は違います。請求が跳ねたなら Claude Code のトークン最適化 を参照してください。

中止ルール：python -c "import claude_agent_sdk" が成功し、TS のインポートがエディタで解決するなら、移行は完了です。それ以降のすべては、リネームの残滓ではなく普通のランタイム問題です。

ofox 経由で Agent SDK を複数モデルに対して動かす

Agent SDK は Anthropic スタイルの endpoint と話しますが、同じエージェントループを OpenAI 互換ゲートウェイに対しても駆動できます。ofox は 1 つの OpenAI 互換 base URL https://api.ofox.ai/v1 を、1 つのキーで Claude、GPT、Gemini を含む 100 以上のモデルに対して公開します。ツール利用ループを自分で組む（または OpenAI スタイルのクライアントで動かす）なら、base_url を ofox に向けることで、SDK を配線し直す代わりに 1 つの文字列変更でモデルを差し替えられます。

from openai import OpenAI

client = OpenAI(api_key="OFOX_API_KEY", base_url="https://api.ofox.ai/v1")
resp = client.chat.completions.create(
    model="anthropic/claude-opus-4.8",   # swap this string to change models
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

ここでの CTA はそれだけです。Claude Agent SDK は、Anthropic ネイティブのエージェントハーネスが欲しいときに正しいツール。OpenAI 互換ゲートウェイは、クライアントコードを書き直さずにプロバイダ間で A/B したいときに正しいツールです。

代替と関連ツール

Agent SDK が合わないなら、正直な選択肢を ofox から順に挙げます。

• ofox API ゲートウェイ（https://api.ofox.ai/v1）：OpenAI 互換、マルチモデル、1 キー。プロバイダの移植性が欲しく、同じループで Claude を GPT や Gemini に対してテストしたいときに良い。
• Claude Agent SDK 直叩き（@anthropic-ai/claude-agent-sdk / claude-agent-sdk）：ネイティブのハーネス。Anthropic の組み込みエージェント機能、MCP サポート、claude_code プリセットが欲しいときに最適。
• Claude Code CLI（@anthropic-ai/claude-code, v2.1.x）：ライブラリではなくターミナルツール。query をアプリコードにインポートする用途ではなく、対話的・スクリプト的な CLI 作業に使う。

FAQ

claude-code-sdk は非推奨ですか？ はい。Python の claude-code-sdk（0.0.25 で凍結）と、かつて @anthropic-ai/claude-code にあった TypeScript SDK は、もう SDK ではありません。claude-agent-sdk と @anthropic-ai/claude-agent-sdk を使ってください。

ClaudeCodeOptions は何に置き換わりましたか？ claude_agent_sdk からインポートする ClaudeAgentOptions です。コンストラクタ引数は同じ、名前が新しいだけ。

なぜ npm install @anthropic-ai/claude-code は通るのにインポートが失敗するのですか？ そのパッケージがいまや SDK ではなく CLI ツール（v2.1.x）だからです。SDK のシンボルは @anthropic-ai/claude-agent-sdk に移りました。

ModuleNotFoundError: No module named ‘claude_code_sdk’ はどう直しますか？ pip uninstall claude-code-sdk、pip install claude-agent-sdk し、claude_agent_sdk からインポートします。Python 3.10+ であることを確認してください。

変わったのは API ですか、それともパッケージ名だけですか？ ほぼ名前だけです。唯一の挙動変更は、v0.1.0+ がデフォルトでは Claude Code のシステムプロンプトを読み込まなくなった点。プリセットでオプトインします。

移行後にモデル ID を変える必要はありますか？ いいえ。モデル文字列はリネームの影響を受けません。

v0.1.0 以降にアップグレードしたらエージェントの挙動が変わったのはなぜですか？ デフォルトのシステムプロンプトが削除されました。claude_code プリセットまたはカスタムの systemPrompt を渡して以前の挙動に戻してください。

@anthropic-ai/claude-code と @anthropic-ai/claude-agent-sdk は同じものですか？ いいえ、別々の 2 パッケージです。一方は CLI、もう一方は SDK です。

今回の更新で確認したソース

• Anthropic「Migrate to Claude Agent SDK」公式ガイド：https://code.claude.com/docs/en/agent-sdk/migration-guide （2026-06-24 確認）
• npm @anthropic-ai/claude-agent-sdk（確認時 0.3.x）：https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk （2026-06-24 確認）
• npm @anthropic-ai/claude-code（CLI、確認時 2.1.x）（2026-06-24 確認）
• PyPI claude-agent-sdk（確認時 0.2.x）：https://pypi.org/project/claude-agent-sdk/ （2026-06-24 確認）
• PyPI claude-code-sdk（0.0.25 で凍結）（2026-06-24 確認）
• anthropics/claude-agent-sdk-python リポジトリと Python 3.10 要件に関する issue 報告（2026-06-24 確認）
• ofox モデルカタログと API base URL：https://ofox.ai/llms-full.txt （2026-06-24 確認）

リネーム後にビルドが壊れたなら、修正はほぼ常に 1 行です：新しいパッケージ名を指すこと。クラスのリネームと消えたデフォルトのシステムプロンプトが、それ以外の唯一の 2 編集で、存在を知ってしまえばどちらも 1 分で済みます。