Claude Agent SDK入門｜5行で自律エージェント構築

結論から言うと、Claude Agent SDKは「Claude Codeの中身を外に取り出したSDK」だ。ターミナルで動くあのエージェントループを、自分のPythonスクリプトやFastAPIアプリの中に埋め込める。しかも、たった5行で。

2026年3月、AnthropicはClaude Code SDKを「Claude Agent SDK」に改名した。名前変更は単なるリブランドではない。Claude Codeという特定の用途から切り離し、任意のドメインで動くエージェントを誰でも組めるようにするという意思表示だ。同じ月にOpenAI Agents SDK、4月にはGoogle ADKが出揃い、エージェントフレームワーク戦国時代が本格的に始まった。

この記事で扱うのは、Pythonでの実装を軸にした実践的な使い方。5行の最小コードから、カスタムツール・Hooks・MCP連携・サブエージェントまで、「触らないと分からないところ」を全部入りで整理した。

Claude Agent SDKとは何か（5行で動く最小実装）

百聞は一見にしかず。これが最小の実装だ。

import anyio
from claude_agent_sdk import query

async def main():
    async for msg in query(prompt="今の東京の天気を調べて要約して"):
        print(msg)

anyio.run(main)

これだけで、Claudeが勝手にWeb検索ツールを呼び、結果を読み、要約を返してくる。query()関数の裏側で動いているのは、Anthropicが本家Claude Codeで使っているのと同じエージェントループだ。

エージェントループとは、「状況を観察→計画→ツール実行→結果を検証→次のアクション」を自律的に繰り返す仕組み。LangGraphのノードグラフや、CrewAIのロールベース分担とは設計思想が違う。Claude Agent SDKはAnthropic自身が本番運用で磨いてきたループをそのまま使わせてくれる、というのが他フレームワークと最大に違うところだ。

Claude Code CLIとSDKの違い

ここで多くの人が躓く。「Claude Codeがあれば十分じゃないの？」という疑問だ。結論は、両者は用途が違う。表で整理する。

平たく言えば、Claude Codeは「自分のための道具」、SDKは「プロダクトに組み込む部品」。SaaSのバックエンドにエージェントを埋め込みたい、夜間バッチで自動レポートを作りたい、Slack Botに"考えて動く"機能を足したい——こういう用途でSDKが活きる。

では実際に動かしてみる。所要時間は3分だ。

インストールから初回実行まで

所要時間3分。公式の手順をそのまま動かす。

ステップ1：Python 3.10以上を用意

Python 3.9では動かない。async/awaitの新しい構文と型ヒントを使っているためだ。python3 --versionで確認しておく。

ステップ2：仮想環境を作って pip install

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

uv派なら1行で済む。

uv init && uv add claude-agent-sdk

ステップ3：APIキーを環境変数に設定

export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxx

キーはAnthropic Consoleで発行する。Amazon Bedrockを使うならAWS_PROFILEを、Google Vertex AIならGOOGLE_APPLICATION_CREDENTIALSを別途セットする。

ステップ4：最初のエージェントを動かす

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        system_prompt="あなたはPython開発者向けのアシスタント。"
    )

    async for msg in query(
        prompt="カレントディレクトリのPythonファイル一覧を作り、list.txtに書き出して",
        options=options,
    ):
        if isinstance(msg, ResultMessage) and msg.subtype == "success":
            print("完了：", msg.result)

anyio.run(main)

実行すると、エージェントが自分でBashツールを呼び、lsでファイル一覧を取り、Writeでlist.txtに書き出す。人間が手順を指示する必要はない。

4つの核機能：カスタムツール / Hooks / MCP / サブエージェント

Agent SDKの真価は、デフォルトのエージェントループに自分の部品を差し込める点にある。差し込み口は4つだ。

4-1. カスタムツール：独自APIを関数として渡す

社内APIを叩かせたい、DBを引かせたい——そういうときは@toolデコレータで関数を書き、MCPサーバーとして束ねて渡す。

from claude_agent_sdk import (
    ClaudeSDKClient, ClaudeAgentOptions, tool,
    create_sdk_mcp_server, AssistantMessage, TextBlock,
)
import asyncio
from typing import Any

@tool("calculate", "数式を評価する", {"expression": str})
async def calculate(args: dict[str, Any]) -> dict[str, Any]:
    try:
        result = eval(args["expression"], {"__builtins__": {}})
        return {"content": [{"type": "text", "text": f"結果: {result}"}]}
    except Exception as e:
        return {"content": [{"type": "text", "text": f"エラー: {e}"}], "is_error": True}

async def main():
    server = create_sdk_mcp_server(
        name="utils", version="1.0.0", tools=[calculate],
    )
    options = ClaudeAgentOptions(
        mcp_servers={"utils": server},
        allowed_tools=["mcp__utils__calculate"],
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query("123 * 456を計算して")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

asyncio.run(main())

ポイントはallowed_toolsの命名規則。mcp__<server名>__<tool名>という二重アンダースコア形式で指定する。ここを間違うとツールが呼ばれずに静かに失敗するので注意。

4-2. Hooks：エージェントの途中に介入する

Hooksは、エージェントループの各段階——ツール実行前、実行後、ユーザー入力時——に任意の関数を差し込む仕組みだ。一番わかりやすい使い方は危険コマンドのブロック。rm -rfが含まれるBash呼び出しを問答無用で止める。

from claude_agent_sdk import (
    ClaudeSDKClient, ClaudeAgentOptions, HookMatcher, HookContext,
)
import asyncio
from typing import Any

async def guard(input_data: dict[str, Any], tool_use_id, context: HookContext):
    if input_data.get("tool_name") == "Bash":
        cmd = str(input_data.get("tool_input", {}))
        if "rm -rf" in cmd:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": "rm -rf を検出したためブロック",
                }
            }
    return {}

async def main():
    options = ClaudeAgentOptions(
        hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[guard])]},
        allowed_tools=["Read", "Write", "Bash"],
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query("キャッシュを全部削除して")
        async for _ in client.receive_response():
            pass

asyncio.run(main())

Hooksは"守衛"であり"監査ログ担当"でもある。本番に出すならPostToolUseでツール実行ログをSlackやログ基盤に流す実装を必ず入れる。理由はシンプルで、エージェントが何をしたか後から追えないと、障害が起きた時の原因特定ができない。

4-3. MCPサーバー連携：既存のエコシステムに乗る

MCP（Model Context Protocol）は、Anthropicが2024年に公開しLinux FoundationのAgentic AI Foundationに寄贈したプロトコル。2026年時点でGitHub MCP、Playwright MCP、Supabase MCP、Notion MCP、Context7 MCPなど500以上のサーバーが公開されている。

Agent SDKは、MCPサーバーをツール源としてそのまま取り込める。GitHub連携したいなら、GitHub MCPを指定するだけ。自分でGitHub APIクライアントを書く必要はない。

options = ClaudeAgentOptions(
    mcp_servers={
        "github": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": "ghp_xxx"},
        }
    },
    allowed_tools=[
        "mcp__github__search_repositories",
        "mcp__github__get_issue",
    ],
)

カスタムツールとMCPの使い分けはこうだ。自社独自のAPI・内部DBは@toolで書く。既に誰かがMCPサーバーを作っているサービス（GitHub/Slack/Notion/Playwrightなど）はMCPを使う。二重に実装する理由はない。

4-4. サブエージェント：役割を分けて精度を上げる

1つのエージェントに大量のコードを読ませると、後半で判断がぶれる。context汚染と呼ばれる現象で、読み込んだ情報が多すぎると優先度の見極めが鈍っていく。解決策はシンプル。役割を分けて、親は指揮者、子は専門職という構造にする。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],
    agents={
        "code-reviewer": {
            "description": "コード品質とセキュリティをレビューする専門家",
            "prompt": "品質問題を指摘し、改善案を出してください",
            "tools": ["Read", "Glob", "Grep"],
        }
    },
)

async for msg in query(
    prompt="code-reviewerエージェントでこのリポジトリをレビューして",
    options=options,
):
    if hasattr(msg, "result"):
        print(msg.result)

親エージェントが必要に応じてcode-reviewerを呼び出す。トークン消費は増える。ただし精度への効果は大きい——親は要約だけ受け取るので、長大なコードを直接読まずに済む。

OpenAI Agents SDK / Google ADKとの違い

2026年4月時点で、主要プレイヤーが出揃った。ざっくり整理する。

個人的に使い分けるなら、Claude Agent SDKは「コードを読む・書く・実行する系」、OpenAI Agents SDKは「対話・文章系の汎用タスク」、Google ADKは「Google Cloud上で業務システムに組み込む」と棲み分けている。どれか1つに絞る必要はない。

料金の目安（実例ベース）

Agent SDK自体は無料だ。課金されるのはその内側で動くClaude API——呼び出すたびにトークン数に応じた従量課金が走る。以下は2026年4月時点の単価と、実際に試して確認した感覚値。

感覚値を出しておく。Sonnetで小規模なコード生成（入力5,000トークン・出力2,000トークン）を1回走らせると約4.5円。1日100回なら月13,500円。個人開発ならHaikuを主戦場にして、精度が要る時だけSonnetに切り替える——それで筆者は月数千円に収めている。

プロンプトキャッシュは必ず入れる。長いシステムプロンプトをキャッシュすると、入力コストが最大90%下がる（Anthropic公式の計測値）。やり方はシンプルで、システムプロンプトのブロックにcache_control: {"type": "ephemeral"}を付けるだけ。5分間キャッシュされ、同じプロンプトを何度投げても課金されるのは最初の1回分だけ。

つまずきポイント5選

Q1. インストールしたのにimportできない

9割が仮想環境の入れ忘れ。which python3を叩く。.venv配下を指していなければ、source .venv/bin/activateが抜けている。

Q2. カスタムツールが呼ばれない

allowed_toolsの命名が間違っている可能性が高い。mcp__<server名>__<tool名>の二重アンダースコア形式を守る。単一アンダースコアで書くと静かに無視される。

Q3. エージェントが無限ループに入る

max_turnsオプションで上限を切る。デフォルトは比較的寛容なので、本番では明示的に10〜20あたりに制限する。

options = ClaudeAgentOptions(max_turns=15, ...)

Q4. Bedrock/Vertex経由だと認証エラーになる

原因は環境変数の優先順位だ。BedrockならCLAUDE_CODE_USE_BEDROCK=1、VertexならCLAUDE_CODE_USE_VERTEX=1を明示する。ここが罠。ANTHROPIC_API_KEYと同時に設定すると、どちらが勝つかは環境次第で揺れる。運用前に必ず片方だけ残すのが安全策。

Q5. ストリーミング出力が途中で止まる

async forループを抜けた後にクライアントが閉じていないか確認。async with ClaudeSDKClient(...)のコンテキストマネージャを使っていれば起きない。直接インスタンス化している場合は要注意。

まとめ：Claude Agent SDKをどう使い分けるか

Claude Agent SDKは、エージェント開発の"ゼロから組み立てる派"ではなく"既にある強いループを使わせてもらう派"の選択肢だ。LangGraphがレゴブロックなら、Claude Agent SDKは既に組み上がったロボットのカスタマイズ口。

自分が今から新規でエージェントを作るなら、コード操作系は無条件にClaude Agent SDK一択だ。MCPのエコシステムがそのまま使えて、Hooksで安全弁を入れられる。この2点だけで他を検討する理由がなくなる。以下は使い分けの補足。

• コード生成・ファイル操作・実行系の自動化 → 迷わずClaude Agent SDK
• GitHub・Slack・Notion連携が中心 → Claude Agent SDK + MCPサーバー
• マルチエージェントで役割分担したい → Claude Agent SDKのサブエージェント機能で十分
• 社内に独自APIが多い → カスタムツール（@toolデコレータ）
• 本番運用で監査ログ必須 → Hooksで全ツール呼び出しを記録

最初の一歩は、この記事の5行コードを動かすこと。それだけで、"エージェントループがどう動くか"が体感できる。公式ドキュメントは動かした後に読み返せばいい。最初から全章を順に読もうとすると、自分の用途と関係ない節で詰まって手が止まる。

関連記事

• Claude Codeの使い方2026｜導入・設定・Cursor比較の実践ガイド
• LangGraph入門2026｜Pythonでエージェントを構築する全手順
• LangChain入門2026｜RAG・Agent実装の最短ルート
• 【2026年最新】AIエージェント完全ガイド｜ビジネス活用から導入ステップまで
• CursorとClaude Codeの設定ファイル完全ガイド

参考書籍