Claude Agent SDK を本番運用するときに必須となる5つの設計パターン(耐久セッション・ハードコスト上限・最小権限ツール・サーキットブレーカ・評価フック)を、Python と TypeScript の実装例とともに解説します。
更新日: 2026年6月8日
Claude Agent SDK を本番運用するには、デモコードをそのまま動かすのではなく、耐久セッション・コスト上限・ツール最小権限・サーキットブレーカ・評価フックという5つの設計パターンを必ず組み込む必要があります。本記事では Anthropic 公式ドキュメントと 2026年6月時点の最新リリース情報に基づき、Python と TypeScript それぞれの実装例、Hooks による副作用制御、サブエージェントの隔離、Managed Agents への移行戦略まで、現場で詰まりやすい論点を体系的に解説します。読み終わる頃には、ステージングでは動くが本番で破綻するエージェントを作る前に、何を最初に固めるべきかが明確になっているはずです。
max_budget_usd によるハードコスト上限、allowed_tools による最小権限ツールスコープが必須。Claude Agent SDK は、Claude Code を動かしているのと同じハーネス(エージェントループ、ツール実行、コンテキスト管理)を、自分のプロセス内で呼び出せるようにした Anthropic 公式ライブラリです。2025年9月に「Claude Code SDK」から改称され、Python と TypeScript の二系統で公開されています。私が初めて触ったときに驚いたのは、ファイル読み書き・bash 実行・Web 検索といった組み込みツールが最初から動く点でした。LangChain や CrewAI のようにラッパーを書き重ねる必要がなく、query() を一回呼ぶだけでエージェントループが回り始めます。
2026年時点の用途は大きく分けて二つあります。一つは社内ツールやバッチ処理に組み込む形 ─ 例えば「PR ごとにテストを書き足すエージェント」を CI に挿す、というような使い方です。もう一つは SaaS のバックエンドに組み込む形で、ユーザのリクエストごとに新しいセッションを起動する用途。前者は MCP コネクタを多用し、後者は durable state とコスト上限の設計が決定的に効いてきます。Anthropic 公式の Agent SDK overview が出発点として最も信頼できる参照先です。
Python は pip install claude-agent-sdk、TypeScript は npm install @anthropic-ai/claude-agent-sdk でインストールできます。Python は 3.10 以上が必須で、それ未満の環境では No matching distribution found for claude-agent-sdk という分かりにくいエラーを出して止まります。TypeScript パッケージは内部で Claude Code のネイティブバイナリをオプショナル依存として同梱するため、別途 Claude Code を入れる必要はありません。
最小コードは以下の通りです。これは何も制限を入れていない「危険な」例で、本番ではこのまま使ってはいけません。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="README.md を読んで日本語で要約して",
options=ClaudeAgentOptions(permission_mode="acceptEdits"),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
1ターン以上続くエージェントには必ず外部ストレージに永続化されたセッションが必要です。SDK が持つセッションオブジェクトはあくまでプロセス内のキャッシュであり、サーバ再起動・コンテナ再スケジュール・例外停止ですべて消えます。私の経験では、ここを「あとで考える」とした案件はほぼ例外なく、本番投入後 2〜3日でユーザから「進捗が消えた」というクレームを受けます。
推奨される構成は、Postgres もしくは Redis に「セッション ID, ユーザ ID, メッセージ JSON, トークン使用量, 作成時刻」を JSONL 風に追記し、それを真実のソースとすることです。SDK セッションを復元したいときは保存しておいたメッセージ列をプロンプトに再注入します。重要なのは、再開時にすべての過去メッセージを送り込むのではなく、要約と直近の N ターンに圧縮することです。コンテキストウィンドウを使い切ると Claude は PreCompact イベントを発火させるので、ここでフックして自前の要約器に置き換えると、Anthropic のデフォルト圧縮よりドメイン特化した記憶を残せます。
類似の設計思想は LangGraph で構築する Agentic RAG の自己修正検索ガイド でも触れていますが、LangGraph がチェックポイントを第一級市民として扱うのに対し、Claude Agent SDK は持続化を呼び出し側に委ねる点で哲学が異なります。
月次の請求アラートはコスト管理ではなく事後の通夜です。本番エージェントには「タスクごと」「ユーザごと」「テナントごと」の三層でハードキャップを入れる必要があります。Claude Agent SDK は max_budget_usd パラメータでセッション単位の上限を設定でき、上限に達するとループは自動停止します。
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
permission_mode="acceptEdits",
max_budget_usd=0.50, # このセッションは 50 セントで打ち切り
max_turns=20, # ループの強制上限
allowed_tools=["Read", "Grep", "Glob"], # 後述パターン3
)
テナントごとの上限はアプリケーション側で実装する必要があります。具体的には、リクエストごとに DB から「当月のテナント累計トークン数」を読み、閾値を超えていたら SDK 呼び出し自体を 429 で蹴る ─ という前段ゲートを置きます。PostToolUse フックで毎ターンの使用量を加算し、Redis にインクリメントしておくと、次のリクエスト判定が一発でできます。Anthropic の最新料金表を参照しつつ、Claude Opus 4.8 と Sonnet 4.6 ではトークン単価が約 5 倍違うため、モデル選択もコスト戦略の一部として扱ってください。
エージェントが触れるすべてのツールは、攻撃面でもあります。Bash ツールを与えれば任意コード実行が、WebFetch を与えれば SSRF や情報持ち出しが可能になります。原則は「タスクに必要な最小集合だけを allowed_tools(Python) / allowedTools(TypeScript)で明示的に渡す」ことです。デフォルトで全ツールが有効になる挙動を頼ってはいけません。
// TypeScript: 読み取り専用エージェント
import { query } from '@anthropic-ai/claude-agent-sdk';
const result = query({
prompt: 'src 配下から TODO コメントを列挙して',
options: {
allowedTools: ['Read', 'Grep', 'Glob'], // 編集系を完全に排除
maxTurns: 10,
maxBudgetUsd: 0.20,
},
});
さらに厳しい制御が必要なら、PermissionRequest フックでツール呼び出しの引数を検査し、特定パスへの書き込みやドメイン外への HTTP を実行時に拒否できます。例えば「/etc や .git 配下への Edit は常にブロック」「WebFetch は社内ドメインのみ許可」といったポリシーは、フックで宣言的に書くと監査もテストも容易です。
Hooks はエージェントのライフサイクルの特定イベントで発火するコールバックで、SDK 本体を改変せずに検証・記録・遮断・変換を差し込めます。Python SDK が現在サポートするイベントは PreToolUse、PostToolUse、PostToolUseFailure、UserPromptSubmit、Stop、SubagentStop、PreCompact、Notification、SubagentStart、PermissionRequest の 10 種類。TypeScript SDK はこれに加えて SessionStart、SessionEnd、WorktreeCreate など、Claude Code 由来のイベントも扱えます。
本番では「いつ・どのセッションで・どのツールが・どんな引数で呼ばれたか」を改ざん不能な形で記録する必要があります。PostToolUse に Matcher を仕込めば、編集系ツールだけを対象にできます。
import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
async def log_file_change(input_data, tool_use_id, context):
file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
session = input_data.get("session_id", "?")
with open("./audit.log", "a") as f:
f.write(f"{datetime.utcnow().isoformat()}Z session={session} file={file_path}\n")
return {}
async def main():
async for message in query(
prompt="utils.py を読みやすくリファクタして",
options=ClaudeAgentOptions(
permission_mode="acceptEdits",
hooks={
"PostToolUse": [
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
]
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
このフック自体は同期的に I/O するためレイテンシに直接影響します。大量並行で動かす場合は、ローカルバッファに積んで別スレッドで S3 や CloudWatch Logs に flush するパターンに置き換えてください。詳しくは Anthropic 公式の Hooks ガイド を参照してください。
サブエージェントは主エージェントが派生させる独立したエージェントインスタンスで、別のコンテキストウィンドウ・別のシステムプロンプト・別のツールセットを持ちます。狙いは三つあります。第一に、コードレビューやテスト生成のような「専門タスク」を切り離して主の会話履歴を汚さない。第二に、並列実行で全体のレイテンシを下げる。第三に、危険なツールを副タスクだけに限定し、主エージェントからは触らせない。
プログラマティックな定義は agents オプションで渡します。主エージェントは各サブエージェントの description を読んで、いつ呼び出すかを自律的に判断します。
import { query } from '@anthropic-ai/claude-agent-sdk';
const result = query({
prompt: '認証モジュールのセキュリティをレビューして',
options: {
agents: {
'code-reviewer': {
description: 'コードレビュー専門。品質・セキュリティ・保守性の観点でレビューする際に使用。',
tools: ['Read', 'Grep', 'Glob'], // 編集権限を持たない
prompt: 'あなたは厳格なセキュアコーディングレビュアです。SQL インジェクション、認可漏れ、ハードコードされた秘密情報を最優先で検出してください。',
},
},
maxTurns: 30,
},
});
ファイルシステムベースの定義(.claude/agents/*.md)も使えます。サブエージェントを git で管理したい場合はこちらが便利です。重要な注意点は、サブエージェントへの唯一のコンテキスト伝達経路は Agent ツールの prompt 文字列だということ。親が読んだファイルパス・エラー文・確定した決定事項は、暗黙に共有されないため、すべて prompt に書き出して渡す必要があります。型安全な引数受け渡しをしたい場合は PydanticAI で型安全な AI エージェントを構築する実践ガイド のアプローチを参考に、Pydantic スキーマを通したラッパーを噛ませると見通しが良くなります。
デモエージェントは「速く失敗する」のに対し、本番エージェントは「ゆっくり、高くつき、ローカルテストをすり抜ける形で失敗する」のが現実です。サーキットブレーカは三層で実装します。
PostToolUseFailure フックでカウンタを更新し、閾値超過時に例外を返してループを停止。max_turns に加え、「直近 5 ターン中 3 ターン以上で同じファイルを編集している」など、振動を検出して打ち切る。Anthropic API は 529 (overloaded) と 429 (rate limit) を返すことがあるため、SDK の外側で指数バックオフ+ジッタを実装し、3 回失敗したら 5 分間そのモデルへのトラフィックを止めて Sonnet にフォールバックする、といったフェイルオーバを組み込んでください。
オフライン評価(ゴールデンセットでの回帰テスト)はデプロイ前のゲートとして、オンライン評価(本番トラフィックでのドリフト検出)はランタイムのガードレールとして、両方を最初から組み込みます。Hooks はオンライン評価の自然な実装場所です。
たとえば Stop フックで最終出力を取得し、軽量な分類器(またはより小さい LLM)で「プロンプトインジェクションの痕跡」「機密情報の漏洩」「ハルシネーションされたツール呼び出し」をスコアリングし、Prometheus にメトリクスを emit します。スコアが閾値を超えた応答はサンプリングして人間レビューキューに送り、月次でファインチューニングまたはシステムプロンプトの改訂に活かす ─ という閉ループが、長期的な品質維持の肝になります。
Anthropic は 2026年4月に Claude Managed Agents をリリースしました。これはハーネス・サンドボックス・セッションログを Anthropic 側で運用する REST API で、Agent SDK と対をなす存在です。公式ガイダンスは「Agent SDK でローカルにプロトタイプし、Managed Agents に移行して本番運用する」というパスを推奨しています。
| 観点 | Claude Agent SDK | Claude Managed Agents |
|---|---|---|
| 実行場所 | 自前インフラ(コンテナ/サーバレス) | Anthropic マネージド |
| セッション永続化 | 自前実装(Postgres/Redis) | マネージド(API 経由で取得) |
| ツールカスタマイズ | 任意の Python/TS 関数を登録可能 | MCP サーバ経由でのみ拡張 |
| VPC 内データアクセス | 容易(プロセス内) | MCP サーバを公開する必要あり |
| スケーリング | 自前のオートスケール設計が必要 | 自動 |
| コスト | トークン課金のみ | トークン + 実行プレミアム |
| 規制要件(SOC2/HIPAA) | 自社で監査範囲を確保 | Anthropic の認証範囲に依存 |
判断基準はシンプルです。機密データが自社 VPC を出てはいけない / カスタムツールが多い / レイテンシの極端な最適化が必要 ─ いずれかに当てはまるなら Agent SDK、それ以外は Managed Agents、と思って大筋外しません。
Claude Code はターミナルで人間が対話的に使う「製品」、Agent SDK は同じハーネスをプログラマティックに呼び出すための「ライブラリ」です。両者は同じ tools とエージェントループを共有しているため、Claude Code で十分に検証したシステムプロンプトをほぼそのまま SDK 側に持ち込めます。これが Anthropic 推奨ワークフロー(「Claude Code で探索 → プロトタイプ → 動くプロンプトを抽出 → SDK に組み込み → デプロイ」)の核心です。
逆に言えば、人間が常時介在し、ターン数が短く、プログラマティック制御が要らないアドホック作業は claude.ai のチャットでよく、わざわざ SDK を立ち上げる必要はありません。SDK はあくまで「コードから会話を駆動し、ツールを与え、構造化された結果を返してほしい」場面の道具です。
LangChain がモデル非依存の抽象化レイヤを提供するのに対し、Claude Agent SDK は Claude Code と同じハーネスをそのまま呼び出すため、ツール・コンテキスト圧縮・サブエージェント周りの挙動が Claude 製品と完全に一致します。マルチプロバイダ前提なら LangChain、Claude を最大限引き出したいなら Agent SDK が適しています。
Hooks は自プロセス内で動くエージェントライフサイクルへのコールバック(検証・ログ・遮断)で、MCP サーバはエージェントが利用できる外部ツール(ブラウザ・GitHub・DB)です。役割の階層が異なるため、同一エージェント内で両方を並行して使うのが普通です。
SessionStart フックは使えますか?2026年6月時点では使えません。SessionStart、SessionEnd、Setup、TeammateIdle、TaskCompleted、ConfigChange、WorktreeCreate、WorktreeRemove は TypeScript SDK のみのサポートです。Python から同等の挙動が必要なら UserPromptSubmit と Stop で代替してください。
できません。2026年5月以降、Anthropic は claude.ai のログインやサブスクリプションのレート上限を外部製品から利用することを利用規約で明示的に禁止しています。本番では API キー認証、または AWS Bedrock / Google Vertex AI / Microsoft Azure AI Foundry のいずれかを必ず利用してください。
SDK 内部には明示的な数値上限はありませんが、Anthropic API のティアごとの同時リクエスト上限と、自前のホスト CPU/メモリが実質的なボトルネックです。経験則として、1 主エージェントあたり同時 5〜10 サブエージェントまでが安定運用しやすく、それ以上は明示的なセマフォで絞ることを推奨します。
n8n、Make、Zapierを2026年版で徹底比較。料金モデル、AIエージェント機能、セルフホスト可否、LangChain統合の違いを整理し、RAG・マルチエージェント・人間承認の実装パターンとZapierからn8nへの段階移行戦略まで、本番運用の知見をもとに解説します。
プロンプトを変えるたびに本番で炎上していませんか。決定論的アサーション70%＋LLM-as-a-Judge 30%のハイブリッドeval構成を、promptfoo・Python・GitHub Actionsの実コードで解説します。
LangGraphを使ったAgentic RAG（自律型RAG）の実装方法を解説。Adaptive RAG・Corrective RAG・Self-Reflective RAGの3パターンを統合し、動的クエリルーティング、文書グレーディング、ハルシネーション検出を備えた自己修正型検索パイプラインをPythonで構築する実践ガイドです。