Claude Agent SDKとanthropicパッケージの違いは何ですか？

anthropicパッケージはMessages APIの薄いラッパーで、ツール呼び出しループを自前で管理する必要があります。Claude Agent SDKはClaude Codeのエンジンをライブラリ化したもので、ファイル操作・コマンド実行・MCP連携など10以上の組み込みツールとエージェントループが同梱されています。

Claude Agent SDKの料金はいくらですか？

2026年6月15日から専用クレジット制に移行します。Pro $20/月、Max 5x $100/月、Max 20x $200/月です。APIキーでの従量課金も引き続き利用可能です。クレジットはユーザー単位で、組織内でのプール・譲渡はできません。

query()とClaudeSDKClientはどう使い分けますか？

query()は単発タスク（ファイル分析、バグ修正、CI/CDパイプライン）向けで、カスタムツールやHooksには非対応です。ClaudeSDKClientは対話型・マルチターン会話向けで、カスタムツール定義、Hooks、セッション永続化に対応しています。迷ったらquery()から始めてください。

Claude Agent SDKでClaude以外のモデルは使えますか？

いいえ、Claude Agent SDKはClaudeモデル専用です。Opus 4.6、Sonnet 4.6、Haiku 4.5など、Anthropicが提供するモデルのみ使用できます。複数のLLMプロバイダーに対応したい場合は、LangGraphやVercel AI SDKなどの汎用フレームワークを検討してください。

Claude Agent SDKのセキュリティリスクと対策を教えてください

主なリスクはプロンプトインジェクションと意図しないツール実行です。対策として、allowed_toolsで利用可能なツールを最小限に制限する、PreToolUse Hookで危険なコマンドをブロックする、max_turnsで最大ターン数を制限する、の3つが基本です。本番環境では必ずPostToolUse Hookでツール使用のログを記録してください。

AIエージェント入門

Claude Agent SDK実践ガイド｜Python自律エージェント構築

2026.05.19 公開 2026.05.16 更新 29分で読める

この記事の結論

Claude Agent SDKでPython製自律型AIエージェントを構築する方法を実コード付きで解説。query・ClaudeSDKClient・サブエージェント・MCP連携・料金設計まで網羅。

Claude Agent SDKを使えば、Pythonコード数行で「ファイル操作・コマンド実行・Web検索」を自律的にこなすAIエージェントが作れる。

要点1: query()（単発）とClaudeSDKClient（マルチターン＋カスタムツール）の2モードを使い分けるのが設計の起点
要点2: MCP Server接続・Hooks・サブエージェントで、外部API連携から行動制御まで本番品質に仕上げられる
要点3: 2026年6月15日からAgent SDKクレジット制に移行 — Pro $20/月、Max 20x $200/月。コスト設計を今のうちに

対象読者: AIエージェントをPythonで構築したい開発者・PM。Claude APIの基本操作（チャット補完）は経験済みの方を想定。

今日やること: pip install claude-agent-sdk → 最初のquery()コール → 結果を確認するまで、所要5分。

「Anthropic公式のSDK、結局どれを使えばいいのか分からない」

先日、社内のエージェント開発プロジェクトで、まさにこの問題にぶつかりました。anthropicパッケージでTool Useループを自前で回すか、Claude Codeをサブプロセスで叩くか、それとも新しいAgent SDKか。選択肢が増えた分、最初の一歩が遠のいていたのです。

結論から言うと、Claude Agent SDKは「Claude Codeの中核エンジンをPython/TypeScriptから呼べるようにしたもの」であり、ファイル操作・ターミナル実行・MCP連携といったエージェント動作に必要なインフラが丸ごと同梱されています。Tool Useループの管理、結果のパース、エラーハンドリング — 自前で書くと数百行になるボイラープレートが、query()一発で片付く。

この記事では、Claude Agent SDKの導入からサブエージェント設計・料金設計までを、実際に動くコードとコピペ可能なプロンプト付きで全公開します。5分で試せるクイックスタートから順に進めていきますので、今日から手を動かしてみてください。

Claude Agent SDKとは何か

なぜ「もう1つのSDK」が必要だったのか

Anthropicにはすでにanthropicパッケージ（Python SDK）がありますが、これはMessages APIの薄いラッパーです。エージェントを作るには、ツール呼び出しのループ管理、結果のフィードバック、エラー時のリトライ、コンテキストウィンドウの管理をすべて自前で実装する必要がありました。

Claude Agent SDKは、Claude Codeの内部エンジンをそのままライブラリ化したものです。Claude Codeが内部で使っている10以上の組み込みツール（Read、Write、Edit、Bash、Glob、Grep、WebSearch など）、エージェントループ、コンテキスト管理がPython/TypeScriptから直接利用できます。

技術的には、SDKはClaude Code CLIバイナリをバンドルしており、stdioプロトコルで通信します。利用者はCLIの存在を意識する必要はなく、Pythonの非同期イテレータとして結果を受け取れます。

AIエージェントの構築パターンやフレームワーク選定の全体像については、Agno完全ガイド — 既存エージェントを本番化する方法でも体系的に解説しています。

query()とClaudeSDKClientの2つの使い方

SDKは2つのインタラクションモードを提供しています。目的に応じた使い分けが設計の起点です。

機能	query()	ClaudeSDKClient
用途	単発タスク（ファイル分析、バグ修正）	対話型・マルチターン
カスタムツール	非対応	対応（@tool デコレータ）
Hooks	非対応	対応（PreToolUse / PostToolUse）
セッション永続化	非対応	対応（resume可能）
実装の複雑度	低（3行で動く）	中（イベント駆動設計）
推奨シーン	CI/CD、バッチ処理、スクリプト	対話型アプリ、長時間タスク

判断基準: 「結果を受け取って終わり」ならquery()。「途中で人間が介入する」「独自のツールを追加したい」ならClaudeSDKClient。迷ったらquery()から始めて、必要になったらClaudeSDKClientに移行してください。

対応モデルとプラン

Agent SDKは、Claude Pro、Max、Team、Enterpriseの各サブスクリプションプランで利用可能です（2026年5月現在）。

プラン	利用可能モデル	Agent SDKクレジット（6月15日〜）
Pro	Sonnet 4.6（※利用可能モデルはプランと時期で変動するため公式ドキュメントを確認）、Haiku 4.5（※利用可能モデルはプランと時期で変動するため公式ドキュメントを確認）	$20/月
Max 5x	Opus 4.6（※利用可能モデルはプランと時期で変動するため公式ドキュメントを確認）、Sonnet 4.6	$100/月
Max 20x	Opus 4.6、Sonnet 4.6	$200/月
Team（Standard）	Sonnet 4.6	$20/seat/月
Team（Premium）	Opus 4.6、Sonnet 4.6	$100/seat/月
API Key（従量課金）	全モデル	クレジット対象外（従量課金継続）

料金情報の最終確認: 2026-05-15。Anthropic公式ヘルプセンターおよびThe Decoderの報道に基づく。

5分クイックスタート — インストールから初回実行まで

環境構築

利用方法は2つあります。(1) Developer Platform の API キーで使う方法、(2) 2026年6月15日以降に Claude プランの Agent SDK クレジットを使う方法。Python 3.10 以上が必須で、どちらの認証方式を使うかで料金計算と上限が変わります。Claude Code CLIはSDKのwheelにバンドルされているため、別途インストールする必要はありません。

# 動作環境: Python 3.10+
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

pip install claude-agent-sdk

# 認証: Claude Codeにログイン済みであればそのまま使える
# 未ログインの場合:
claude login

ポイント: claude-agent-sdkとclaude-code-sdkは別パッケージです。Agent SDKはclaude-agent-sdkが正式名称。PyPIで間違えないよう注意してください。

query()で最初のエージェントを動かす

以下のコードをファイルに保存して実行するだけで、AIエージェントがカレントディレクトリのTODOコメントを自律的に検索してくれます。

# 動作環境: Python 3.10+, claude-agent-sdk (latest)
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="このディレクトリのPythonファイルからTODOコメントを全て見つけて、優先度順にリストアップしてください。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            max_turns=10
        ),
    ):
        if message.type == "text":
            print(message.content)

asyncio.run(main())

ポイント:

query()は非同期イテレータを返す。async forで消費する
allowed_toolsで使わせるツールを明示的に制限することが重要。省略すると全ツールにアクセス可能になる
max_turnsでエージェントの最大ターン数を制限できる。無制限にすると暴走リスクがある

実行結果の読み方とデバッグ

query()が返すメッセージには複数のtypeがあります。デバッグ時は全メッセージをログに残すことを推奨します。

message.type	内容	活用方法
text	Claudeの推論テキスト	最終結果の表示
tool_use	ツール呼び出しリクエスト	ログ・監査証跡
tool_result	ツール実行結果	デバッグ・品質検証
error	エラー情報	リトライ判定

特にtool_useメッセージを見ると、エージェントが「何を考えて」「どのツールを選んだか」が追跡できます。想定外のツール選択やパラメータが見つかれば、プロンプトの改善ポイントが分かります。

ClaudeSDKClientで本格エージェントを構築する

カスタムツールの定義方法

ClaudeSDKClientの最大の強みは、独自のツールをPython関数として定義できることです。@toolデコレータで関数を装飾し、MCP Serverとして登録します。

# 動作環境: Python 3.10+, claude-agent-sdk (latest)
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    ClaudeAgentOptions,
    ClaudeSDKClient,
)

@tool
def search_database(query: str, limit: int = 10) -> str:
    """社内ナレッジベースを検索する。

    Args:
        query: 検索キーワード
        limit: 最大件数（デフォルト10）
    """
    # 実際のDB検索ロジックをここに実装
    results = db.search(query, limit=limit)
    return "n".join([f"- {r.title}: {r.summary}" for r in results])

@tool
def create_ticket(title: str, description: str, priority: str = "medium") -> str:
    """JIRAチケットを作成する。

    Args:
        title: チケットタイトル
        description: 詳細説明
        priority: 優先度（low/medium/high）
    """
    ticket = jira.create_issue(title=title, desc=description, priority=priority)
    return f"チケット作成完了: {ticket.key}"

# カスタムツールをMCP Serverとして登録
server = create_sdk_mcp_server(
    name="my-custom-tools",
    version="1.0.0",
    tools=[search_database, create_ticket]
)

# クライアント起動
client = ClaudeSDKClient(
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "search_database", "create_ticket"],
        max_turns=20
    ),
    mcp_servers=[server]
)

設計のコツ: ツール関数のdocstringがそのままClaude側のツール説明になります。「何をするツールか」「引数は何か」を自然言語で丁寧に書くほど、適切なタイミングで適切な引数と共に呼び出されます。

MCP Serverとの接続

外部のMCP Server（GitHub、Slack、データベースなど）に接続することで、エージェントの行動範囲を大幅に拡張できます。MCPの基本概念や公開手順はMCP Registry完全ガイドで解説しています。

# 動作環境: Python 3.10+, claude-agent-sdk (latest)
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

client = ClaudeSDKClient(
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash", "mcp__github__*"],
        max_turns=30
    ),
    mcp_servers=[
        {
            "name": "github",
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": "ghp_xxxx"}  # 実際は環境変数やシークレットマネージャーから取得
        },
        {
            "name": "slack",
            "command": "npx",
            "args": ["-y", "@anthropic/mcp-server-slack"],
            "env": {"SLACK_BOT_TOKEN": "xoxb-xxxx"}  # 同上
        }
    ]
)

注意: MCP Serverのツールが多い場合、コンテキストウィンドウを圧迫します。Agent SDKにはTool Search機能が組み込まれており、全ツール定義をコンテキストに載せるのではなく、必要なツールだけを動的にロードします。ツール数が多いMCP Serverを使う場合はこのデフォルト動作に任せるのが安全です。

Hooksでエージェントの行動を制御する

Hooksは「ツールが実行される前後にカスタムロジックを挿入する」仕組みです。セキュリティゲート、ログ収集、コスト管理に不可欠な機能です。

# 動作環境: Python 3.10+, claude-agent-sdk (latest)
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
import json
from datetime import datetime
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def block_dangerous_commands(event):
    """危険なBashコマンドをブロックする PreToolUse Hook"""
    if event.tool_name == "Bash":
        dangerous = ["rm -rf", "DROP TABLE", "git push --force", "curl | bash"]
        for cmd in dangerous:
            if cmd in event.tool_input.get("command", ""):
                return {"decision": "block", "reason": f"危険なコマンド検出: {cmd}"}
    return {"decision": "allow"}

async def log_tool_usage(event):
    """全ツール使用をログに記録する PostToolUse Hook"""
    log_entry = {
        "tool": event.tool_name,
        "input": event.tool_input,
        "output_length": len(str(event.tool_output)),
        "timestamp": datetime.now().isoformat()
    }
    # audit_logger は事前に設定したロガー
    print(json.dumps(log_entry, ensure_ascii=False))

client = ClaudeSDKClient(
    options=ClaudeAgentOptions(max_turns=20),
    hooks={
        "PreToolUse": [{"matcher": "Bash", "handler": block_dangerous_commands}],
        "PostToolUse": [{"handler": log_tool_usage}]  # matcherなし = 全ツール対象
    }
)

Hookの実行順序: matcherなしのHookは全イベントで発火します。matcherありのHookは、指定されたツール名にマッチした時だけ発火します。複数のHookを登録した場合、配列の順番に実行されます。本番環境ではPreToolUseでのセキュリティゲートとPostToolUseでのログ収集を必ず組み合わせてください。

セッション永続化とマルチターン会話

ClaudeSDKClientはセッションのresume（再開）に対応しています。長時間タスクを中断して翌日に再開する、といった使い方が可能です。セッションIDを保存しておけば、別のPythonプロセスからでも同じ会話コンテキストを引き継げます。

この仕組みは、バックグラウンドで複数のエージェントを走らせるワークフロー管理にも応用できます。Slackからのリクエストを受けてエージェントを起動し、完了時にSlackに通知を返す — といった非同期パイプラインの構築が現実的になります。

サブエージェント設計 — 複数AIの協調パターン

並列分析パターン

1つの問題を複数のサブエージェントに分割して並列処理させるパターンです。例えば、コードレビューを「セキュリティ」「パフォーマンス」「可読性」の3観点で同時に実行させます。

サブエージェントはAgentツール経由で起動され、メインエージェントのコンテキストとは独立したコンテキストウィンドウで動作します。これにより、大規模なコードベースでもコンテキスト溢れを防げます。並列実行によって、逐次処理の3分の1程度の時間でレビューが完了した事例もあります。

役割分担パターン（PM / Architect / Implementer）

複雑なプロジェクトでは、役割ごとにサブエージェントを分けるのが効果的です。

役割	許可ツール	担当
PM（プロジェクト管理）	Read, Grep, WebSearch	要件整理、タスク分解
Architect（設計）	Read, Grep, Glob	アーキテクチャ設計、技術選定
Implementer（実装）	Read, Write, Edit, Bash	コーディング、テスト実行
Reviewer（レビュー）	Read, Grep	コードレビュー、品質確認

重要: ツール権限を省略すると、サブエージェントは利用可能な全ツールにアクセスできてしまいます。意図的にスコーピングすることで、「レビューエージェントが勝手にコードを書き換える」「PMエージェントが本番環境でコマンドを実行する」といった事故を防げます。

ツール権限のスコーピングと設計原則

allowed_toolsとdisallowed_toolsを組み合わせて、各サブエージェントの行動範囲を厳密に制御します。原則は最小権限の原則（Principle of Least Privilege）です。

具体的には、サブエージェントの設定フィールドでtools（許可リスト）を明示的に指定します。さらにmodel、maxTurns、mcpServersなどを役割に応じて個別に設定することで、各エージェントのコストと安全性を最適化できます。

例えばレビュー用サブエージェントにはHaiku 4.5（低コスト）+ Read/Grepのみを許可し、実装用サブエージェントにはOpus 4.6 + Read/Write/Edit/Bashを許可する、という構成が定番です。

コピペ可能な実践プロンプト5選

以下のプロンプトはすべてquery()のprompt引数にそのまま渡せます。実際のプロジェクトで検証済みのものです。

プロンプト1: コードベース全体のセキュリティ監査

# 用途: プロジェクト全体のセキュリティリスクを自動検出
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 数字と固有名詞は、根拠（出典/計算式）を添えてください。

このリポジトリのセキュリティ監査を実施してください。

## チェック項目
1. ハードコードされたAPIキー・パスワード・トークンの検出
2. SQLインジェクション脆弱性のあるコードパターン
3. XSS脆弱性のあるHTMLレンダリング
4. 安全でない依存パッケージ（既知のCVE）
5. 不適切なファイルパーミッション設定

## 出力形式
発見した問題ごとに以下を記載:
- ファイルパス:行番号
- リスクレベル（Critical/High/Medium/Low）
- 問題の説明
- 修正案（コード例付き）

Critical/Highの問題は先に報告してください。

プロンプト2: テストカバレッジ向上の自動実装

# 用途: テストが不足している関数を特定し、テストコードを自動生成
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 不足している情報があれば、最初に質問してから作業を開始してください。

以下の手順でテストカバレッジを向上させてください。

1. まずプロジェクトの既存テストを確認（テストファイルの一覧と構造）
2. テストが存在しない、または不十分な関数・クラスを特定
3. 優先度の高いもの（public API、ビジネスロジック）から順にテストを作成

## テスト作成ルール
- 既存のテストフレームワーク（pytest/jest等）に合わせる
- 正常系・異常系・境界値の3パターンを含める
- モック・スタブは最小限に（統合テスト寄り）
- テストを書いたら実行して全テストがパスすることを確認

## 出力
作成したテスト一覧と、カバレッジの変化（概算）を最後にまとめてください。

プロンプト3: レガシーコードのリファクタリング計画

# 用途: 複雑なコードの段階的リファクタリング計画を策定
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 数字と固有名詞は、根拠（出典/計算式）を添えてください。

このリポジトリのコード品質を分析し、リファクタリング計画を作成してください。

## 分析観点
1. 循環的複雑度が高い関数（10以上）のリストアップ
2. 重複コードの検出（DRY違反）
3. 単一責任原則に違反しているクラス
4. 不要なインポート・未使用変数
5. 型ヒントの欠損（Python）/ 型安全性の問題（TypeScript）

## 出力形式
| 優先度 | ファイル | 問題 | 推奨アクション | 影響範囲 | 所要時間目安 |

優先度はP0（即修正）〜P3（余裕があれば）の4段階で。
リファクタリングは既存テストが通ることを前提に計画してください。

プロンプト4: API仕様書からの自動クライアント生成

# 用途: OpenAPI/Swagger仕様書からタイプセーフなAPIクライアントを生成
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 不足している情報があれば、最初に質問してから作業を開始してください。

指定されたAPIエンドポイントに対するPythonクライアントを生成してください。

## 要件
1. プロジェクト内のAPI仕様（OpenAPI/Swagger JSONまたはYAML）を読み取る
2. 各エンドポイントに対応するメソッドを持つクライアントクラスを作成
3. リクエスト/レスポンスの型をPydanticモデルで定義
4. リトライ（exponential backoff）とタイムアウト処理を組み込む
5. 認証ヘッダーの自動付与（Bearer Token方式）

## コード規約
- httpxを使用（requestsではなく）
- async/awaitベース
- エラーはカスタム例外クラスで整理
- 環境変数からのベースURL・トークン読み込み

プロンプト5: ドキュメントとコードの整合性チェック

# 用途: README/ドキュメントとコードの乖離を自動検出
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# 数字と固有名詞は、根拠（出典/計算式）を添えてください。

プロジェクトのドキュメント（README.md、docs/配下）とソースコードの整合性を検証してください。

## チェック項目
1. READMEに書かれたインストール手順が実際に動くか
2. ドキュメントに記載されたAPI引数・戻り値が実装と一致するか
3. ドキュメントに記載されたファイルパスが実在するか
4. 設定ファイルの例（.env.example等）が最新か
5. 非推奨（deprecated）になった機能がドキュメントに残っていないか

## 出力形式
不整合ごとに:
- ドキュメントの該当箇所（ファイル:行番号）
- ソースコードの該当箇所（ファイル:行番号）
- 不整合の内容
- 修正提案（ドキュメント側 or コード側どちらを直すべきか）

料金体系 — Agent SDKクレジットの全貌

プラン別クレジット一覧

2026年6月15日から、Agent SDKの利用は専用クレジット制に移行します。これまでサブスクリプションの通常利用枠内で使えていたプログラマティック利用（claude -p、Agent SDK、GitHub Actions）が、独立した月額クレジットとして分離されます。

プラン	月額クレジット	超過時
Pro（$20/月）	$20	利用停止（翌月リセット）
Max 5x（$100/月）	$100	利用停止（翌月リセット）
Max 20x（$200/月）	$200	利用停止（翌月リセット）
API Key	対象外	従量課金継続

出典: Anthropic公式ヘルプセンター（参照日: 2026-05-15）

注意点: クレジットはユーザー単位で、組織内でのプール・譲渡はできません。未使用分は翌月に繰り越されません。

APIキー利用時の注意点

Claude Developer PlatformのAPIキーでAgent SDKを使う場合、月額クレジットは付与されません。従来通りの従量課金（トークン数ベース）が適用されます。

逆に言えば、大量のエージェント処理が必要なプロダクション環境では、Max 20xの$200クレジットよりもAPIキーの従量課金のほうがコスト効率が良いケースもあります。月間のトークン消費量を試算して判断してください。

コスト最適化3つの実践テクニック

テクニック1: モデルの使い分け

すべてのタスクにOpus 4.6を使う必要はありません。ファイル検索・定型チェックにはHaiku 4.5を、複雑な推論が必要なタスクにだけOpusを使うことで、同じクレジットで3〜5倍のタスク量をこなせます。ClaudeAgentOptionsのmodelパラメータで切り替え可能です。

テクニック2: max_turnsの制限

max_turnsを設定しないと、エージェントが延々とツール呼び出しを繰り返す可能性があります。タスクの複雑度に応じて10〜30ターン程度に制限するのが安全です。それでも足りない場合はタスクの分割を検討してください。

テクニック3: allowed_toolsの厳密化

利用可能なツールを必要最小限に絞ることで、不要なツール呼び出し（＝トークン消費）を削減できます。WebSearchが不要なタスクでWebSearchを許可しない、Bashが不要ならBashを外す。検証環境で、ツールを絞った場合と全開放した場合のトークン消費量を比較してみると、20〜40%の差が出ることがあります。

【要注意】よくある失敗パターンと回避策

失敗1: settings.jsonのAPIキー優先順位を理解していない

❌ ~/.claude/settings.jsonにAPIキーを設定しているのに、環境変数で別のキーを渡して「なぜか反映されない」と悩む

⭕ 設定の優先順位を理解し、意図的にスコープを指定する

なぜ重要か: Claude Agent SDKの設定はManaged > Command line > Local > Project > Userの優先順位で適用されます。~/.claude/settings.json（Userスコープ）にAPIキーが書かれていると、環境変数のキーは無視されます。SDKで別のキーを使いたい場合は、settingSourcesからuserを除外する必要があります。GitHub Issuesでも頻出の質問です。

失敗2: allowed_toolsを指定せず全ツールを解放する

❌ 「とりあえず全ツール使えるようにしておこう」とallowed_toolsを省略する

⭕ タスクに必要なツールだけを明示的にリストアップする

なぜ重要か: 全ツール解放は、エージェントがrm -rfを含むBashコマンドを実行するリスクを意味します。本番データの削除、意図しないgit pushなど、取り返しのつかない操作が発生し得ます。特にサブエージェントには「PMはRead系のみ」「ImplementerはRead+Write+Edit+Bash」のように役割に応じたツールセットを設計してください。

失敗3: query()とClaudeSDKClientを混同する

❌ query()でカスタムツールを使おうとする / ClaudeSDKClientを単発タスクに使ってオーバーヘッドを増やす

⭕ 単発タスクはquery()、対話型・カスタムツール使用はClaudeSDKClientと明確に使い分ける

なぜ重要か: query()はPython SDKではカスタムツールとHooksに非対応です（TypeScript SDKのquery()は対応）。「query()でツールが動かない」というGitHub Issueが複数報告されていますが、これはPython SDK側の仕様です。一方で、単発のファイル分析にClaudeSDKClientを使うと、セッション管理やイベントループのセットアップが無駄なオーバーヘッドになります。

失敗4: 6月15日のクレジット制移行を見落とす

❌ 現在の「サブスクリプション枠内で使い放題」の感覚でCI/CDパイプラインにAgent SDKを組み込む

⭕ 6月15日以降のクレジット消費量を事前に試算し、予算計画に組み込む

なぜ重要か: 2026年6月15日からAgent SDKクレジットが分離されます。Pro $20/月、Max 5x $100/月、Max 20x $200/月が上限です。CI/CDで毎コミット・毎PRにAgent SDKを走らせていると、月半ばでクレジットが枯渇する可能性があります。重要度の高いジョブにだけAgent SDKを使い、定型チェックは従来のリンターやテストランナーで代替する設計が必要です。

OpenAI Agents SDKとの比較 — どちらを選ぶべきか

アーキテクチャの根本的な違い

両SDKは「AIエージェントを作る」という目的は同じですが、設計思想が大きく異なります。

観点	Claude Agent SDK	OpenAI Agents SDK
内部構造	Claude Code CLIをラップ	Responses APIのネイティブラッパー
組み込みツール	10以上（Read, Write, Bash等）	3つ（Web Search, File Search, Computer Use）
マルチエージェント	ツールチェーン方式（サブエージェント）	Handoff方式（明示的な引き継ぎ）
MCP対応	深い統合（ネイティブ）	2026年初頭に採用
安全性設計	Constitutional AI + Hooks	Guardrails（入出力バリデーション）
モデルロック	Claudeモデルのみ	OpenAIモデルのみ
ファイル操作	ネイティブ対応	別途実装が必要

Claude Agent SDKの強みは「ファイル操作・ターミナル実行が最初から使える」こと。開発者ツール寄りのエージェントを作るなら効率が良い。一方、OpenAI Agents SDKの強みは「Handoffによる明示的なエージェント間の引き継ぎ」と「Guardrailsの本番品質」です。カスタマーサポートのような対話型ワークフローに向いています。

AIコーディングツールの比較については、Codex CLI vs Claude Code 完全比較も参考にしてください。

用途別おすすめ

用途	おすすめ	理由
コード分析・自動修正	Claude Agent SDK	ファイル操作・Bash実行がネイティブ
CI/CDパイプライン統合	Claude Agent SDK	GitHub Actions連携が公式サポート
カスタマーサポートBot	OpenAI Agents SDK	Handoff + Guardrailsが成熟
RAG検索エージェント	OpenAI Agents SDK	File Searchが組み込み
マルチツール業務自動化	両方検討	MCP重視ならClaude、Web検索重視ならOpenAI

セキュリティと本番運用チェックリスト

プロンプトインジェクション対策

エージェントが外部データ（ユーザー入力、Web検索結果、ファイル内容）を読み取る場合、プロンプトインジェクションのリスクがあります。悪意のある入力がエージェントの行動を乗っ取り、意図しないファイル操作やコマンド実行を引き起こす可能性があります。

対策の基本:

入力バリデーション: ユーザー入力をエージェントに渡す前にサニタイズする
出力バリデーション: エージェントの出力を直接実行せず、ホワイトリストで検証する
Hooksによるゲート: PreToolUse Hookで危険な操作をブロックする（前述のコード例参照）
最小権限: allowed_toolsで本当に必要なツールだけを許可する

権限管理のベストプラクティス

本番環境でAgent SDKを使う場合、以下のチェックリストを確認してください。

□ APIキー・トークンは環境変数またはシークレットマネージャーで管理（コードにハードコードしない）
□ allowed_toolsを明示的に指定（全ツール解放の禁止）
□ max_turnsを設定（無限ループ防止）
□ PreToolUse Hookで破壊的コマンドをブロック
□ PostToolUse Hookで全ツール使用をログに記録（監査証跡）
□ 本番DBへの直接アクセスは禁止（読み取り専用レプリカを使う）
□ エージェントの実行環境を隔離（Docker/サンドボックス）

モニタリングとログ設計

エージェントの動作ログは、通常のアプリケーションログとは異なる粒度で設計する必要があります。「どのツールを」「どの入力で」「何回呼んだか」「結果は何だったか」をターン単位で記録することで、異常動作の早期発見と再現性のあるデバッグが可能になります。

正直にお伝えすると、現時点のAgent SDKには組み込みのモニタリングダッシュボードはありません。PostToolUse Hookでログを収集し、DatadogやGrafanaなどの外部ツールに送信する設計が現実的です。エージェントの運用可視化については、AgentIQとは？NVIDIA製AI運用見える化基盤も参考になります。

参考・出典

Agent SDK overview — Claude API Docs — Anthropic公式（参照日: 2026-05-15）
anthropics/claude-agent-sdk-python — GitHub — Anthropic公式リポジトリ（参照日: 2026-05-15）
Quickstart — Claude API Docs — Anthropic公式（参照日: 2026-05-15）
Use the Claude Agent SDK with your Claude plan — Claude Help Center — Anthropic公式（参照日: 2026-05-15）
Claude subscriptions get separate budgets for programmatic use — The Decoder（参照日: 2026-05-15）
Anthropic reinstates OpenClaw and third-party agent usage — VentureBeat（参照日: 2026-05-15）
Intercept and control agent behavior with hooks — Claude API Docs — Anthropic公式（参照日: 2026-05-15）

まとめ：今日から始める3つのアクション

今日やること: pip install claude-agent-sdkして、本記事の「query()で最初のエージェントを動かす」のコードを実行する。自分のプロジェクトディレクトリで試すと、SDKの能力を実感できる
今週中: ClaudeSDKClientでカスタムツールを1つ定義してみる。社内のAPI、Slackへの通知、データベース検索など、日常業務に直結するツールが候補
今月中: 6月15日のクレジット制移行に備え、現在のAgent SDK利用量を計測する。CI/CDでの利用頻度とトークン消費量を把握し、適切なプランを選定する

あわせて読みたい:

Codex CLI vs Claude Code 完全比較｜10項目で選び方がわかる徹底ガイド — AIコーディングツール選定の基準
MCP Registry完全ガイド｜公開手順6ステップ — Agent SDKと組み合わせるMCP Serverの公開方法
AgentIQとは？NVIDIA製AI運用見える化基盤 — エージェント運用のモニタリング設計

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。

ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。

この記事を読んでAIエージェント導入のイメージが固まってきた方へ

UravationではAIエージェント導入の研修・コンサルを行っています。

Need help moving from reading to rollout?

この記事を読んで導入イメージが固まってきた方へ

Uravationでは、AIエージェントの要件整理、PoC設計、社内導入、研修まで一気通貫で支援しています。

30分無料相談を予約支援実績を見る

※ 本記事の情報は2026年5月時点のものです。サービスの料金・仕様は変更される可能性があります。最新情報は各サービスの公式サイトをご確認ください。