Claude Agent SDK（旧Claude Code SDK）とは？使い方・移行・料金を解説【2026年版】

「Claude Code SDK」で検索してこの記事にたどり着いた方の多くは、いま正式名称がClaude Agent SDKに変わっていることに戸惑っているはずです。Anthropicは2025年9月にこのSDKを「Claude Code SDK」から「Claude Agent SDK」へ改称しました。パッケージ名もPython版がclaude-code-sdkからclaude-agent-sdkへ、npm版が@anthropic-ai/claude-codeから@anthropic-ai/claude-agent-sdkへ変わっており、古い記事のインストールコマンドはもう通りません。この記事では、改称後のClaude Agent SDKが何で、Claude Code本体とどう違い、Python/TypeScriptでどう使い、旧SDKからどう移行し、2026年6月に発表され施行当日に一時停止された料金変更の現状はどうなっているのかを、公式ドキュメントとGitHubリポジトリの記述に沿って整理します。バージョンや価格は更新が速いため、確定値は公式での確認を前提に読み進めてください。

まとめ：Claude Agent SDKの要点（旧Claude Code SDK）

先に全体像を押さえます。Claude Agent SDKは、Claude Codeを動かしているのと同じエージェントループ・ツール群・コンテキスト管理を、PythonとTypeScriptからプログラムで呼び出せるようにした公式ライブラリです。「Claude Code SDK」は旧名で、2025年9月に改称されました。導入はpip install claude-agent-sdk（Python 3.10以上）またはnpm install @anthropic-ai/claude-agent-sdkで、Python/TypeScriptともquery()関数を起点に数行からエージェントを起動できます。旧claude-code-sdkからの移行はインポート名と型名（ClaudeCodeOptions→ClaudeAgentOptions）の付け替えが中心です。2026年6月にはAgent SDK経由のプログラム利用をサブスク枠から別建てのクレジットへ切り出す変更が発表されましたが、6月15日の施行当日にAnthropicが一時停止を発表し、別枠化は現時点で実施されていません（いまも従来どおりサブスク枠から消費）。今後の料金改定の論点になり得るため、本番運用では公式の料金ページで最新を確認してください。以下、それぞれを順に掘り下げます。

Claude Agent SDKとは何か（旧Claude Code SDKからの改称）

Claude Agent SDKは、ファイルの読み書き・コマンド実行・Web検索・コード編集などを自律的にこなすAIエージェントを、開発者が自分のコードから組み立てるためのAnthropic公式SDKです。チャットUIや単発のメッセージAPIと違い、Claudeが「考える→ツールを使う→結果を見て次を決める」というエージェントループを回す部分まで含めて提供されるのが核心です。Claude Codeというコーディング支援ツールが内部で使っているハーネス（実行基盤）を、そのままライブラリとして開放したもの、と捉えると位置づけがつかめます。

名称が「Code」から「Agent」へ変わったのは、用途がコーディング支援に限らずカスタマーサポート・調査・業務自動化といった汎用エージェント構築へ広がったことを反映しています。つまり単なる名前替えではなく、対象範囲の宣言でもあります。Anthropicが提供する基本的なAPIの仕組みを先に把握したい場合は、Anthropic API（Claude API）の料金とAPIキー取得の解説を併読すると、SDKがその上にどう乗っているかが整理できます。

Claude CodeとClaude Agent SDKの違い

混同しやすいのが、CLIツールの「Claude Code」と、ライブラリの「Claude Agent SDK」の関係です。両者は競合ではなく、土台と利用形態の違いです。Claude Codeはターミナルで人間が対話的に使うアプリケーションで、Claude Agent SDKはその実行基盤をPython/TypeScriptのコードから呼ぶための部品です。npm版のSDKはClaude Codeのネイティブバイナリを依存として同梱するため、SDKを入れればCLIを別途インストールする必要はありません。

判断の目安はシンプルです。自分でコードを書く作業を速くしたいならClaude Code、自社サービスにエージェント機能を組み込むならClaude Agent SDK、と役割で分けます。Claude Code本体の機能や料金を先に知りたい場合はClaude Codeのできること・使い方・料金の解説記事が起点になります。

導入とインストール（pip / npm）

導入は環境ごとに1コマンドです。古い記事に残る@anthropic/claude-codeやclaude-code-sdkはもう解決しないため、必ず改称後のパッケージ名を使います。

Pythonでのインストールと最小コード

Python版はPyPIのclaude-agent-sdkで、Python 3.10以上が必要です。認証はANTHROPIC_API_KEY環境変数に発行済みのAPIキーを入れておけば、SDKが自動で参照します。最小の実行は次の形です。

pip install claude-agent-sdk

# main.py
import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="プロジェクト直下のREADME.mdを3行で要約して"):
        print(message)

anyio.run(main)

query()は応答メッセージを順次返す非同期イテレータです。1回の指示で完結する処理に向き、戻り値をそのまま後続処理へ流せます。

TypeScript/Node.jsでのインストールと最小コード

TypeScript版はnpmの@anthropic-ai/claude-agent-sdkです。前述のとおりClaude Codeバイナリを同梱するため追加インストールは不要です。

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

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

for await (const message of query({
  prompt: "src配下のTypeScriptでHello Worldを書いて",
})) {
  console.log(message);
}

導入後にエラーが出る場合、原因の大半はAPIキー未設定かパッケージ名の打ち間違いです。ANTHROPIC_API_KEYが読めているかを最初に確認します。

基本的な使い方（query関数とClaudeAgentOptions）

SDKの中心はquery()関数と、その挙動を決めるClaudeAgentOptions（TypeScriptではオプションオブジェクト）です。プロンプトだけを渡せばデフォルト設定で動きますが、本番では使えるツールやシステムプロンプトを明示的に絞るのが定石です。

許可ツールの制御（allowed_toolsとdisallowed_tools）

allowed_toolsは自動承認するツールの許可リストで、ここに挙げたツールは確認なしで実行され、挙げていないツールはpermission_modeの判定に回ります。重要な注意点として、allowed_toolsはツールセットからツールを取り除くものではありません。特定ツールを明確に禁止したいときはdisallowed_toolsを使います。エージェントにファイル書き込みやコマンド実行を任せる場合、この2つで権限境界を先に決めておかないと、想定外の操作が走るリスクが残ります。

システムプロンプトと設定ソース（system_promptとsetting_sources）

system_promptにはプリセット（例："claude_code"）や独自の指示を指定できます。プロジェクト直下のCLAUDE.mdをエージェントに読ませたいときはsetting_sources=["project"]を指定します。CLAUDE.mdはプロジェクト固有のルールや前提を記述する設定ファイルで、これを読み込ませることで、誰が実行しても同じ前提でエージェントが動くようにそろえられます。

旧Claude Code SDKからの移行手順

すでに旧claude-code-sdkでコードを書いていた場合、移行は破壊的変更を含みますが範囲は限定的です。やることはパッケージの入れ替えと、インポート名・型名の付け替えが中心です。

# 旧
pip uninstall claude-code-sdk
# 新
pip install claude-agent-sdk

コード側では、Python型のClaudeCodeOptionsがClaudeAgentOptionsへ改名されています。インポート元をclaude_agent_sdkに変え、この型名を置換すれば多くのケースは動きます。デフォルト挙動が一部変わっている項目もあるため、システムプロンプトや設定ソースの読み込みは移行後に実挙動を確認するのが安全です。旧→新の移行は2026年時点で多くの開発者が直面しうる実務課題で、Anthropicも公式の移行ガイドを提供しています。最新の差分はその移行ガイドで確認してください。

2026年の料金変更（発表→施行当日に一時停止）：Agent SDKクレジットの別枠化

本番運用で押さえておきたいのが、いったん発表されたものの施行当日に止まった課金変更の経緯です。Anthropicは2026年5月に、Claude Agent SDK経由のプログラム利用をサブスクリプションの利用枠とは別建ての月次クレジットへ切り出す方針を発表し、2026年6月15日に施行する予定でした。ところがAnthropicは施行当日の6月15日に、この変更を一時停止（pause）すると発表し、別枠化は現時点で実施されていません。つまり、Agent SDK・claude -pのヘッドレス実行・Claude CodeのGitHub Actions連携・サードパーティ製アプリ経由の利用は、いまも従来どおりサブスクリプションの利用枠から消費されます。

発表時点の案内では、別枠クレジットはAPI料金ベースで消費され、付与額はProプランに月$20相当、Max 5xに月$100相当、Max 20xに月$200相当（いずれも発表時点の案内値）とされていました。ただしこれらは施行されないまま一時停止になった値であり、現在有効な料金体系ではありません。Anthropicはプランを見直したうえで、将来の変更時には事前告知すると説明しています。

この一件が示すのは、対話でClaude Codeを使う分とSDKで自動化した分のコスト切り分けが、今後の改定で再び論点になり得るということです。エージェントをループで回す設計はトークン消費が読みにくいため、本番投入前に小さく回して消費量を実測しておくのが現実的です。クレジットの別枠化が再開されるか、付与額やモデル別単価がどうなるかは流動的なので、確定値は必ず公式の料金ページで確認してください。

主なユースケースと向かない場面

Claude Agent SDKが効くのは、人手だと反復が多く、かつ判断とツール操作が混ざる作業です。コードレビューコメントの自動生成、テストログの要約、社内ドキュメントの取得と要約、CI/CDでのリリースノート作成などが典型です。サブエージェントで専門タスクを並列処理し、コンテキストを分割して扱える点も、規模の大きい処理で効いてきます。

一方で、採用すべきでない場面もはっきりしています。入力から出力が一意に決まる単純な定型処理に、エージェントループを使うのは過剰です。プロンプトを投げて1回答えが返ればよい用途なら、エージェント基盤を挟まず通常のメッセージAPIを直接叩く方が、コストもレイテンシも有利です。「自律的にツールを選んで複数ステップを進める必要があるか」を導入判断の線引きにすると、無駄なクレジット消費を避けられます。MCP連携で外部システムへ広げる設計を検討するなら、エージェントの実行環境設計そのものが成果を左右します。Claude Code側の拡張機能の全体像はClaude Codeの拡張機能を整理した記事が参考になります。

APIキーの安全な管理

SDKはANTHROPIC_API_KEYを参照するため、このキーの扱いがセキュリティの要になります。キーはソースコードに直書きせず、ローカルでは.env、CI/CDではGitHub ActionsのSecretsやクラウドのシークレットマネージャに置きます。.gitignoreに.envを必ず加え、誤コミットを防ぎます。Agent SDKは課金が別枠化された分、キーが漏れたときの想定被害が読みやすくなった一方で、自動実行ゆえに気づかぬうちにクレジットを消費される懸念もあります。開発用と本番用でキーを分け、定期ローテーションとログ上のマスキングをセットで運用するのが堅実です。VS Code上で扱う場合の構成はClaude Code for VS Codeの一般提供に関する記事も合わせて確認できます。

よくある質問

Claude Code SDKとClaude Agent SDKは別物ですか？

別物ではなく、同じSDKの旧名と新名です。2025年9月にClaude Code SDKがClaude Agent SDKへ改称されました。中身は名称変更に加えて機能追加が入っており、パッケージ名・型名が変わっています。旧名で書かれた記事のコマンドは現行では通らないため、新しいパッケージ名で導入してください。

pip install claude code は通りますか？

現行はpip install claude-agent-sdkです。旧名のclaude-code-sdkやclaude-sdkといった名称では現行版を取得できません。Python 3.10以上が必要なので、合わせてランタイムのバージョンも確認してください。

Claude CodeとClaude Agent SDKはどちらを使うべきですか？

自分の作業を手元で速くしたいならCLIのClaude Code、自社サービスやスクリプトにエージェント機能を組み込むならClaude Agent SDKです。npm版SDKはClaude Codeバイナリを同梱するため、SDKを入れればCLIを別途用意する必要はありません。

PHPやほかの言語から使えますか？

公式SDKが提供されているのはPythonとTypeScript/Node.jsです。PHPなど他言語からは、公式の専用SDKではなくAnthropic APIを直接HTTPで呼ぶ形になります。エージェントループまで含めて自前で組む必要があるため、まずはPython/TypeScriptでの利用が現実的です。

料金はサブスクに含まれますか？

2026年6月時点では、Agent SDK経由のプログラム利用は従来どおりサブスクリプションの利用枠から消費されます。Agent SDK利用を別建ての月次クレジットへ切り出す変更が2026年5月に発表され6月15日施行予定でしたが、Anthropicが施行当日に一時停止を発表したため、別枠化は実施されていません。発表時点ではPro月$20相当・Max 5x月$100相当・Max 20x月$200相当（いずれも案内値）とされていました。再開の有無や付与額・単価は流動的なので、最新は公式の料金ページで確認してください。あわせて、ループエンジニアリングについても解説しています。

関連記事

• Claude Codeとは？できること・使い方・料金とコード解析の実力【2026年版】
• Anthropic APIとは？概要と基本的な仕組みを解説
• 【2026年版】Claude Codeの6つの拡張機能をまとめて整理！それぞれの役割と使い分け方も解説
• AnthropicがClaude Code for VS Codeを一般提供開始、AIコーディング支援拡張機能が正式リリース
• Web版Claude Codeの使い方と魅力を徹底解説：オンラインAIコーディング環境の基本操作ガイド