Claude Agent SDK完全ガイド｜Anthropicが「Claude Codeの頭脳」を開発者に公開（2026年）

「Claude Codeが自律的にコードを書けるなら、その仕組みを自分のアプリに組み込めないか」

この問いに対し、Anthropicが2026年1月28日に正式な回答を出した。Claude Agent SDKのローンチだ（出典：Anthropic engineering「Building agents with the Claude Agent SDK」、2026年1月28日）。

Claude Codeを動かしているエージェントループとツール群を、Python/TypeScriptのライブラリとして開発者に提供するというものだ。「最強のコーディングエージェント」として知られるClaude Codeの「頭脳」が、誰でも使えるパッケージになった。

なぜ今、Agent SDKなのか

Anthropicは長らく「モデルを提供する会社」として振る舞ってきた。Claude APIを叩いてテキストを生成させる、それが開発者との主な接点だった。

Claude Codeの登場（2025年）がその構図を変えた。Claude CodeはAPIの上に「自律的に動くループ」を実装したアプリケーションだ。プロンプトに対して「考える→ツールを使う→結果を検証する→また考える」を繰り返し、複数ファイルにまたがるコード変更や複雑なリファクタリングを人間の介入なしにこなす。

その中核部分、エージェントループとツール群を外に出したのがClaude Agent SDKだ。

Anthropicは公式ブログでこう説明している。

「Claude Code SDKをClaude Agent SDKにリネームした。コーディング以外の用途でも多くのエージェントが構築されていることを反映したものだ」

（出典：Anthropic engineering「Building agents with the Claude Agent SDK」）

名前の変更は機能の拡張も意味する。コーディング専用だったSDKが、より汎用的なエージェント構築基盤として再定義された。

Claude APIとの根本的な違い

誤解されやすいポイントから先に整理しておく。

Claude Agent SDKはAnthropicのAPIクライアント（anthropic-sdk-pythonや@anthropic-ai/sdk）とは別物だ。

項目	Claude API（クライアントSDK）	Claude Agent SDK
役割	テキスト生成のAPI呼び出し	エージェントの自律動作ループ全体
ツール実行	開発者が実装する	組み込み済み（Read/Write/Bash等）
繰り返し	1ターンの応答	課題が完了するまで自律的に継続
コンテキスト管理	開発者が管理	SDKが自動管理
カスタムツール	ファンクションコーリングで実装	Pythonデコレーターで定義
MCP統合	別途実装が必要	設定ファイル1行で接続

端的に言えば、Claude APIは「エンジンのみ」、Claude Agent SDKは「エンジン・ギア・ハンドル・カーナビがセットになった完成車」だ。

主な機能

組み込みツール

デフォルトでClaudeが使えるツール群はClaude Codeと同一だ（出典：Claude Agent SDK overview）。

ツール名	機能
Read	ファイルの読み取り
Write	ファイルの書き込み
Edit	ファイルの部分編集
Bash	シェルコマンドの実行
WebFetch	URLのコンテンツ取得
WebSearch	Web検索
Glob	ファイルパターン検索
Grep	コンテンツ検索

allowed_toolsパラメーターで使用するツールを絞り込める。本番環境では最小権限の原則に従い、必要なツールのみを許可するのが基本だ。

カスタムツール

Pythonの関数をデコレーターで定義するだけで、Claudeが呼び出せるカスタムツールになる（出典：Claude Agent SDK reference - Python）。

from claude_agent_sdk import query, ClaudeAgentOptions

# カスタムツールの定義（デコレーターは不要、関数として渡す）
async def get_stock_price(symbol: str) -> dict:
    """株価を取得する"""
    # 実際のAPIコールをここに記述
    return {"symbol": symbol, "price": 150.0}

async def main():
    async for message in query(
        prompt="AAPLの株価を確認して、100ドルを超えていたら教えて",
        options=ClaudeAgentOptions(
            custom_tools=[get_stock_price],
            allowed_tools=["Bash"],
        ),
    ):
        print(message)

カスタムツールはプロセス内のMCPサーバーとして動作する。別プロセスを立ち上げる通常のMCPサーバーと違い、同一Pythonプロセス内で動くため、既存の変数やオブジェクトを直接使えるのが利点だ。

MCPサーバー統合

外部サービスとの連携はMCPで行う（MCP実践ガイドで詳しく解説している）。Slack、GitHub、Google Drive、Asanaなどの公式MCPサーバーを設定ファイルに追加するだけで、OAuthやAPI認証の実装なしにClaudeがそれらのサービスを操作できる（出典：Claude Agent SDK overview）。

サブエージェント

大きなタスクを小さなサブエージェントに分割して並列実行できる。Claude Codeのマルチエージェント活用で触れたパターンをSDK経由でも実装可能だ。ただし後述するが、サブエージェントのメモリ管理は注意が必要だ。

ファイルチェックポイントとロールバック

エージェントの実行中にファイル変更のチェックポイントを記録し、特定の時点まで巻き戻せる機能だ。「やり直し」が可能なエージェントを構築できる。

思考深度の制御

effortパラメーターで"low"・"medium"・"high"・"max"を選択できる。単純なタスクには低エフォートを使い、トークン消費とコストを抑えられる（出典：Claude Agent SDK reference）。

最小構成：10行で始める

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="src/auth.py のバグを見つけて修正して",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"],
        ),
    ):
        print(message)

asyncio.run(main())

インストールはpip install claude-agent-sdkだ。Python 3.10以上とNode.js 18以上が必要で、Claude Code CLIが内部でバンドルされる（出典：Claude Agent SDK Quickstart）。

実行前にAnthropicのAPIキーを環境変数に設定しておく必要がある。

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxx"
python main.py

TypeScript版はnpm install @anthropic-ai/claude-agent-sdkで使える。

実際の活用事例

フィンテック：独自データベースへの接続

あるフィンテックスタートアップは、Claude Agent SDKを使ってClaudeに自社のリスクデータベースへの読み取りアクセスを付与した。カスタムツールとしてget_risk_score()を定義し、AIが意思決定の根拠にできるデータを直接参照できるようにした。

結果として「単なるチャットボットではなく、自社データを参照して動くオペレーショナルレイヤー」になったと報告している（出典：Claude Agent SDK developer experience review 2026、2026年）。

Apple XcodeとのSDK統合

AnthropicはAppleとのXcode向けClaude Agent SDK統合を発表している。プロジェクト全体のコードを理解した上で、複数ファイルにまたがるリファクタリングやSwiftUIインターフェースの生成、アーキテクチャ一貫性の確保をXcode内から実行できるとされている（出典：Anthropic「Apple’s Xcode now supports the Claude Agent SDK」）。iOS・macOS開発者にとっては特に注目のパートナーシップだ。

DevOps：Pulumi/インフラ自動化

DevOpsエンジニアの間では、Pulumi TypeScriptと組み合わせてインフラ定義を自動生成する用途での利用が増えている。OIDC認証・ComponentResource抽象化・適切な出力構造といったパターンを事前に学習させ、反復的なインフラ作業をエージェントに任せる形だ（出典：Pulumi Blog「The Claude Skills I Actually Use for DevOps」）。

開発者コミュニティの声

ポジティブな評価

「SDKはシンプルだ。デコレーターでツールを定義して、query()を呼ぶだけ。パラメーター検証・エラー処理・コンテキスト注入はSDKが全部やってくれる」

（出典：DEV Community「Claude Agent SDK: Build Agents That Work Like Claude Code」）

「Claude Agent SDKの真価は『AIにコンピューターを渡す』ことだ。テキスト生成APIではなく、ターミナル・ファイルシステム・Webへのアクセスを持つランタイム環境だ」

（出典：Medium「The Definitive Guide to the Claude Agent SDK」、2026年2月）

「Claude Code CLIをヘッドレスで使うことも、SDKとしてコードに埋め込むことも、どちらもできる。本当の価値はこの二択から先にある」

（出典：Medium「Claude Code Deep Dive - The SDK Strikes Back」by Gigi Sayfan、2026年3月）

課題・注意点の声

「複数のサブエージェントを使うとメモリが尽きる。リソース管理を正しく実装しないとOOM（メモリ不足）になる」

（出典：Claude Agent SDK developer experience review）

「サンドボックス化とファイルシステムのユーザー間分離が複雑だ。マルチテナントのサービスに組み込む場合は特に設計が難しい」

（出典：Claude Agent SDK developer experience review）

Claude Code CLIとの使い分け

Claude Code 2026年アップデートまとめでも触れたが、CLIとSDKは競合ではなく用途が異なる。

観点	Claude Code CLI	Claude Agent SDK
主な使い方	ターミナルから対話形式で作業	自分のアプリ・サービスに組み込む
向いている人	個人の開発作業を加速したいエンジニア	AIエージェント機能を製品に組み込みたい開発者
カスタマイズ	CLAUDE.mdファイルとスキル	コードで自由に定義
実行モデル	人間が指示して承認	完全自律（許可設定に応じて）
MCP接続	~/.claude.jsonで設定	ClaudeAgentOptionsで設定

Cursor Automationsガイドで紹介したCursor Automationsと組み合わせる場合は、「イベントドリブンな起動はCursor Automations、自律的な処理ロジックはClaude Agent SDK経由で実装」というアーキテクチャが考えられる。

MCP vs A2Aプロトコル比較で解説したA2Aプロトコルとの組み合わせも、複数エージェントが協調するシステムでは検討に値する。

注意点と落とし穴

バージョン0.1.x台である: 2026年3月時点でアクティブに開発中だ。破壊的変更が発生する可能性があり、本番環境ではバージョンをピン止めしてテストを行うこと。

トークン消費の増大: エージェントループはツールを何度も呼び出す。シンプルなAPIコールに比べてトークン消費が大きくなるため、effortを"low"や"medium"に設定して必要以上に消費しない設計を心がける。

サブエージェントのメモリ問題: 複数のサブエージェントを並列実行する際は、メモリ使用量を事前に把握してリソース制限を設定しておく必要がある。テスト不足のまま本番に投入するとOOMで落ちるリスクがある。

プロンプトインジェクションのリスク: Claudeが外部データ（GitHubのIssue、Webページの内容など）を読み込んでアクションを実行する場合、悪意ある指示が混入するリスクがある（出典：Claude Codeセキュリティアナウンス）。信頼できないデータソースを扱う場合はサンドボックス設定を徹底すること。

allowed_toolsの最小化: デフォルトでは全ツールが使える。本番環境ではallowed_toolsでタスクに必要なツールのみを許可する最小権限設計が基本だ。

PMとしての判断

自分がこのSDKをプロダクトに採用するかどうかと問われれば、「課題が明確なら使う、そうでなければまず使わない」と答える。

Claude Agent SDKは強力だが、銀の弾丸ではない。「AIをプロダクトに組み込みたい」という漠然とした動機で入れても、トークンコストとデバッグコストが上がるだけになりかねない。

自分なりの判断基準を整理するとこうなる。以下の3条件がすべて揃う場合、Claude Agent SDKは有力な選択肢になり得る。

1. ツール実行が必須: ファイルI/O・コマンド実行・外部API呼び出しが組み合わさる
2. 複数ステップの自律判断が必要: 1回のプロンプトで完結しない、試行錯誤を伴う作業
3. 繰り返し発生する: 1回限りのタスクならCLIで手動実行で十分

逆に言えば、どれか1つでも欠ける場合は通常のClaude APIか、CLIの手動実行から始めた方がシンプルだ。SDKの強みはエージェントループにある。そのループが不要なユースケースに使うのは過剰設計になる。

個人のフリーランス案件での試し方としては、繰り返し発生するファイル操作やレポート生成を1つ自動化するところから始めるのが無難だ。小さなスコープでトークン消費と精度を確認してから、用途を広げていく判断で十分だと思っている。

---

免責事項: 本記事の情報は2026年3月31日時点のものです。Claude Agent SDKはバージョン0.1.x台で活発に開発中であり、仕様は予告なく変更されることがあります。本記事の内容はAnthropicの公式見解ではなく、筆者の調査・見解に基づくものです。本番導入前に必ず公式ドキュメントで最新仕様を確認し、自社環境でのテストを行ってください。本記事の情報に基づく実装・運用で生じた損害について、著者および発行者は一切の責任を負いません。最新情報はClaude Agent SDK公式ドキュメントおよびGitHubリポジトリを参照してください。記事内の開発者コメントは各メディア・コミュニティで公開されたものです。Anthropicとの商業的関係はありません。