Akira

Posted on May 19 • Originally published at apidog.com

Claudeマネージドエージェント vs Agent SDK (2026年): 選び方

Claude で本番環境向けの AI エージェントを出荷する場合、最初に決めるべきことは「エージェントループをどこで動かすか」です。Anthropic に Claude マネージドエージェントでループとサンドボックスをホストさせるのか、それとも Claude エージェント SDK を使って自分のプロセス内で実行するのか。この選択は、アーキテクチャ、コスト、データレジデンシー、オンコール体制に直接影響します。

今すぐ Apidog を試す

結論

次の基準で選びます。

Claude マネージドエージェント: Anthropic にエージェントループ、サンドボックス、セッション状態をホストさせたい場合。長時間実行される非同期ジョブや、インフラ運用よりランタイム料金を支払う方が合理的な場合に向いています。
Claude エージェント SDK: ループを自社プロセス内に保持し、ツール実行、データレジデンシー、監査、コスト構造を細かく制御したい場合に向いています。

どちらも MCP と Claude モデルに対応しています。違いは「モデル」ではなく「運用責任の境界」です。

はじめに

2026年に「AI エージェントを構築する」と言う場合、それは単にチャット補完の周りに while ループを書くことではありません。実際の本番エージェントは、決済 API、チケット管理 API、在庫サービス、社内検索 API、MCP サーバーなどを呼び出して作業します。

つまり、エージェントの信頼性はモデルだけでなく、エージェントが呼び出す API とツールの信頼性に依存します。

Claude で本番エージェントを作る場合、主な選択肢は2つです。

Claude マネージドエージェント

Anthropic がエージェントループ、サンドボックス、セッションをホストする REST API。
Claude エージェント SDK

Python または TypeScript のライブラリとして、自社プロセス内でエージェントループを実行する方式。

どちらを選ぶ場合でも、エージェントが呼び出す API は事前にモック、契約テスト、デバッグしておくべきです。たとえば Apidog を使えば、エージェントが依存する API をモックし、契約テストを実行し、MCP サーバーをエージェントと同じ呼び出し方で検証できます。

ホスト型側を詳しく確認したい場合は、Claude マネージドエージェントガイドも参考になります。

Claude マネージドエージェントとは

Claude マネージドエージェントは、Anthropic が管理するインフラ上で動くホスト型エージェントランタイムです。自分でエージェントループ、サンドボックス、ツール実行レイヤーを作る代わりに、エージェント定義を作成し、Anthropic に実行させます。

2026年4月にパブリックベータとして提供され、リクエストには managed-agents-2026-04-01 ベータヘッダーが必要です。SDK 利用時はこのヘッダーが自動設定されます。

基本概念

Claude マネージドエージェントは、次の4つで構成されます。

エージェント: モデル、システムプロンプト、ツール、MCP サーバー、スキルの定義。
環境: Python、Node.js、Go などのパッケージやネットワークルールを含むコンテナテンプレート。
セッション: 環境内で実行されるエージェントインスタンス。タスク、会話履歴、永続ファイルシステムを持ちます。
イベント: アプリとエージェント間で流れるメッセージ。ユーザー入力、ツール結果、ステータス更新などを SSE でストリーミングします。

実装フロー

基本的な流れは以下です。

エージェントを作成する
実行環境を設定する
セッションを開始する
ユーザーメッセージをイベントとして送信する
応答やツール要求をストリーミングで受け取る
必要に応じて追加イベントを送信し、実行中のエージェントを制御する
イベント履歴を取得して監査やデバッグに使う

マネージドエージェントは、Bash、ファイル操作、WebSearch、WebFetch、MCP サーバー接続などの組み込みツールを提供します。

向いているワークロードは以下です。

数分から数時間動く非同期タスク
多数のツール呼び出しを含む処理
クラウドサンドボックスで安全に実行したい処理
インフラ運用を最小化したいチーム
会話間で状態を保持したいセッション型ワークロード

AWS 上の Claude Platform でも利用できますが、機能可用性やセッション動作に違いがあるため、クラウド制約がある場合は公式ドキュメントで確認してください。

注意点

カスタムツールの扱いは SDK と異なります。Claude はツール呼び出しを要求しますが、実行するのはアプリケーション側です。結果はイベントストリーム経由で返します。つまり、ループとサンドボックスはホストされますが、実際のカスタムツール実行は自社環境に残ります。

また、成果物やマルチエージェントなど一部の機能は研究プレビューとして別途アクセス申請が必要です。ベータ機能を前提に本番設計しないようにしてください。

エージェント設計全体の考え方は、エージェント AI アーキテクチャに関する記事でも整理されています。

Claude エージェント SDK とは

Claude エージェント SDK は、Claude Code を支えるエージェントループ、ツール、コンテキスト管理を Python または TypeScript から使えるライブラリです。以前は Claude Code SDK と呼ばれていましたが、コーディング以外のエージェント用途も対象にするため名称変更されました。

インストールは以下です。

pip install claude-agent-sdk

または

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

API キーを設定すると、エージェントループは自社プロセス内で実行されます。

最小構成の考え方

Python では、プロンプトと利用可能なツールを含むオプションを渡して query() を呼び出し、ストリーミングされたメッセージを処理します。

通常のクライアント SDK では、次のようなツール実行ループを自分で書く必要があります。

while response.stop_reason == "tool_use":
    # ツール呼び出しを解析
    # 自分でツールを実行
    # 結果を Claude に返す
    pass

Claude エージェント SDK は、このループ、ツール実行、コンテキスト管理をライブラリとして提供します。

SDK が提供する主な機能

組み込みツール

Read、Write、Edit、Bash、Glob、Grep、WebSearch、WebFetch、バックグラウンドスクリプト監視、AskUserQuestion など。
フック

PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit などのライフサイクルポイントでコールバックを実行できます。監査、ログ、ポリシー適用、ブロック処理に使えます。
サブエージェント

専門タスク用のエージェントを生成できます。メッセージには parent_tool_use_id が含まれるため、どのサブエージェントが何をしたかを追跡できます。
MCP 対応

Model Context Protocol 経由で、データベース、ブラウザ、内部 API などを接続できます。
権限管理

安全なツールを事前承認し、危険なツールをブロックし、機密アクションには承認を要求できます。
セッション管理

セッション ID を保存して後から再開したり、フォークして別の選択肢を検証したりできます。状態はファイルシステム上の JSONL として保持されるため、自社で所有できます。

SDK は Claude Code のファイルシステム設定も読み取れます。

.claude/skills/

CLAUDE.md

また、Anthropic API だけでなく、Amazon Bedrock、AWS 上の Claude Platform、Google Vertex AI、Azure AI Foundry 経由の認証もサポートします。既存のクラウド契約内で推論を維持したい場合に重要です。

実装から始めたい場合は、Claude プランで Claude エージェント SDK をセットアップするガイドや、独自の Claude Code を構築するウォークスルーが参考になります。

請求に関する注意

2026年6月15日以降、Agent SDK と

claude -p

のサブスクリプションプランでの使用は、対話型利用制限とは別の月額 Agent SDK クレジットから引き落とされます。

料金や制限は変わる可能性があります。ブログ記事内の数値ではなく、Anthropic の最新規約を直接確認してください。

直接比較: マネージドエージェント vs エージェント SDK

コストを見積もる前に、Anthropic の料金ページとマネージドエージェントのドキュメントを確認してください。

要素	Claude マネージドエージェント	Claude エージェント SDK
ループの実行場所	Anthropic 管理インフラ	自社プロセス、自社インフラ
インターフェース	REST API + SSE イベントストリーム	Python または TypeScript ライブラリ
制御性	設定とイベントで制御	フック、権限、インプロセスロジックで細かく制御
コストモデル	Claude トークン料金 + アクティブセッション時間のランタイム料金	Claude トークン料金 + 自社で実行するコンピューティング費用
運用負担	低い。サンドボックス、スケーリング、セッションストアを運用しない	高い。サービス、サンドボックス、監視、スケーリングを自社で運用
可観測性	ホスト型イベントログを取得可能	フック、ログ、トレーシングを自社で実装
レイテンシ	ホスト型ランタイムへのネットワークホップあり	ツールやデータに近い場所で実行可能
データレジデンシー	サンドボックスとセッション状態は Anthropic 側、または AWS オプション	ファイル、状態、ツール実行を自社環境に保持
カスタムツール実行	Claude が要求し、アプリが実行して結果を返す	Python / TypeScript 関数としてインプロセス実行
向いている用途	長時間実行、非同期、インフラ軽量な本番エージェント	ローカルプロトタイプ、厳格なデータ制御、内部サービスに近いエージェント

コスト

マネージドエージェントは、標準の Claude トークン料金に加えて、アクティブなセッション時間に対するランタイム料金が発生します。ツール呼び出しの間に待機している時間も、アクティブセッションとして課金対象になる可能性があります。

SDK には Anthropic の時間単位ランタイム料金はありません。ただし、自社サーバー、オートスケーリング、サンドボックス、監視、オンコール運用のコストが発生します。

紙の上で SDK が安く見えても、運用負荷まで含めると逆転することがあります。

運用負担

マネージドエージェントは、サンドボックス、セッションストア、スケーリングを Anthropic 側に寄せられます。小規模チームや非同期ジョブ中心のサービスでは大きな利点です。

SDK はその逆です。すべてを制御できますが、すべてを運用する必要があります。VPC 内でプライベート DB に接続する必要がある場合や、既存の監査基盤と密に統合したい場合に向いています。

データレジデンシー

SDK を使う場合、ツール実行とセッション状態は自社インフラ内に残ります。Claude に送られるのはモデル推論に必要な情報です。

マネージドエージェントでは、サンドボックスとイベントログが Anthropic の環境、または条件付きで AWS 側に存在します。規制対象データを扱う場合、この一点だけで SDK を選ぶことがあります。

可観測性

マネージドエージェントは、取得可能なホスト型イベントログを提供します。

SDK はフックを提供しますが、ログ、トレース、監査基盤への接続は自社実装です。柔軟性は高いですが、初期実装の手間があります。

エージェントが呼び出す API のテストとデバッグ

ホスティング方式に関係なく、エージェントの信頼性は API と MCP サーバーに依存します。

たとえば、推論は正しくても、決済 API が不安定であれば返金エージェントは不安定です。出荷前に次の3レイヤーをテストしてください。

1. API 契約

エージェントが呼び出すすべてのツールは、スキーマを持つ API として扱います。

やること:

エンドポイントをモックする
リクエストスキーマを定義する
レスポンススキーマを定義する
正常系と異常系を契約テストする
CI またはスケジュール実行で回す

Apidog を使うと、決済サービスやチケットサービスのモックを作成し、エージェントが期待するスキーマを定義し、契約テストを継続実行できます。

具体的な失敗モードは、API を呼び出す AI エージェントのテスト方法に関するガイドで解説されています。

2. MCP サーバー

マネージドエージェントも SDK も、外部ツールを MCP 経由で接続できます。MCP サーバー自体も API サービスです。

検証すべき点:

公開されているツール一覧
各ツールの入力スキーマ
各ツールの出力スキーマ
タイムアウト時の挙動
エラー時のレスポンス形式
エージェントが扱いやすい構造化データになっているか

Apidog を使用した MCP サーバーのテストでは、MCP サーバーが公開するツールを列挙し、それぞれを直接試す方法が説明されています。

Apidog には AI エージェントと A2A デバッガーも含まれているため、エージェントが生成するリクエストとレスポンスを実際に確認できます。

3. エージェント自身のリクエストパターン

エージェントは人間とは違う呼び出し方をします。

よくあるパターン:

短時間で同じ API を複数回呼ぶ
失敗時に過剰リトライする
部分的な情報だけで検索 API を叩く
推論ループ中に同じエンドポイントを繰り返し呼ぶ
504 後に成功済み操作を再実行する

本番前に、モック API に対して現実的なチケットや履歴データをリプレイし、エージェントが実際に送るリクエストを観察してください。

マネージドエージェントではループが隠れるため、イベントログと API レベルのテストが重要です。SDK ではフックでループを計測できますが、それでも API 契約テストは必要です。

エージェントを顧客データに接続する前に、Apidog をダウンロードして依存 API を検証しておくと安全です。

意思決定フレームワーク

次の質問に順に答えると選びやすくなります。

Claude マネージドエージェントを選ぶべき場合

エージェントが数分から数時間動く
非同期ジョブが中心
多数のツール呼び出しがある
ジョブランナー、サンドボックス、セッションストアを運用したくない
小規模チームで、運用人数が制約になっている
ホスト型イベントログを使いたい
データとコンプライアンス上、Anthropic または AWS 側のサンドボックスを許容できる
ベータ機能や研究プレビューの制約を受け入れられる

Claude エージェント SDK を選ぶべき場合

エージェントを自社 VPC 内で実行する必要がある
プライベート DB や内部 API に近い場所で動かしたい
セッション状態を第三者環境に置けない
カスタム権限、監査フック、ポリシー制御が必要
データレジデンシーや規制要件が厳しい
Bedrock、Vertex、Azure など既存クラウド契約で推論を扱いたい
ローカルで素早くプロトタイプを作りたい

よくある移行パス

実務では、次の流れがよくあります。

Claude エージェント SDK でローカルプロトタイプを作る
フック、ツール、MCP 接続、API 契約を検証する
本番運用コストと制御要件を比較する
運用削減の価値が大きければマネージドエージェントへ移行する

ただし、これは設定変更ではありません。ライブラリ方式から REST + イベント方式に変わり、カスタムツール実行やセッション状態の扱いも変わります。移行はプロジェクトとして計画してください。

モデルやコーディングエージェントも比較している場合は、2026年版 Claude と Codex の比較も参考になります。

実際のユースケース

支払返金エージェント

要件:

サポートチケットを読む
取引を検索する
返金ポリシーを確認する
決済 API を呼び出して返金する
チケットに結果を書き戻す
金銭操作の監査証跡を残す

このケースでは SDK が有力です。

理由:

決済サービスの近く、つまり自社 VPC 内で実行したい
セッション状態を自社インフラ外に出したくない
PreToolUse フックで「一定額以上の返金には人間承認が必要」というルールを強制できる
すべての API 呼び出しを監査ログに残せる

実装前にやるべきこと:

Apidog で決済 API と元帳 API をモックする
返金、検索、チケット更新の契約テストを作る
過去1週間分のチケットをモックに対してリプレイする
エージェントが実際に送るリクエストを確認する
504 やタイムアウト時の再実行挙動を検証する

特に返金処理では、成功済み操作をリトライで再実行するバグが致命的です。API レベルのテストは必須です。

非同期サポートチケットトリアージエージェント

要件:

毎日数千件のサポートチケットを処理する
チケットを分類する
関連ログを取得する
返信案を作る
解決またはエスカレーションする
各チケットの処理に数分かかる
データの機密性は比較的低い

このケースではマネージドエージェントが向いています。

理由:

長時間実行、非同期、多数のツール呼び出しという形状に合う
小規模チームがワーカーフリートを運用しなくてよい
ホスト型イベントログでチケット単位のトレースを取得できる

ただし、依存 API の検証は必要です。

ロギング API をモックする
チケットシステム MCP サーバーをテストする
スキーマ変更時に契約テストが落ちるようにする
エージェントの実トラフィックを観察する

ホスティングがマネージドでも、API の正確性は自社の責任です。

ファイアウォール内の内部データ運用エージェント

要件:

「昨日失敗した ETL パーティションをバックフィルする」などの内部依頼を処理する
内部ジョブ API を呼ぶ
修復スクリプトを実行する
ステータスを報告する
内部 API はパブリックインターネットに出ていない
データは機密性が高い

この場合は SDK が自然な選択です。

理由:

エージェントがプライベートサービスに到達できる場所で実行される必要がある
セッション状態をサードパーティのサンドボックスに置けない
MCP サーバーを内部ネットワーク内で接続できる
SDK フックで実行コマンドを既存の監査パイプラインに送れる

このケースでは「自社プロセス内で動く」ことが好みではなく要件です。

AI エージェントが API コンシューマーになっている背景は、新しい API コンシューマーとしての AI エージェントでも説明されています。

本番前チェックリスト

出荷前に最低限確認すべき項目です。

アーキテクチャ

[ ] エージェントループをどこで実行するか決めた
[ ] セッション状態の保存場所を明確にした
[ ] カスタムツールの実行場所を明確にした
[ ] MCP サーバーの接続方式を決めた
[ ] ネットワーク境界とデータレジデンシーを確認した

セキュリティ

[ ] 危険なツール呼び出しをブロックできる
[ ] 金銭操作やデータ変更に承認フローがある
[ ] ツール実行ログを監査できる
[ ] API キーと認証情報の管理方法を決めた
[ ] エラー時に機密情報を返さない

テスト

[ ] すべての依存 API をモックした
[ ] リクエストとレスポンスの契約テストを作成した
[ ] MCP サーバーの各ツールを単独でテストした
[ ] タイムアウトとリトライを検証した
[ ] 実データに近いトラフィックをリプレイした

運用

[ ] コストモデルを見積もった
[ ] イベントログまたはフックログを取得できる
[ ] 障害時のオンコール責任を決めた
[ ] ベータ機能への依存を確認した
[ ] Anthropic の最新料金と利用条件を確認した

結論

マネージドエージェントとエージェント SDK の選択は、API 設計に見えますが、実際には運用とデータガバナンスの判断です。

要点は以下です。

マネージドエージェントはループとサンドボックスをホストする
SDK はループを自社プロセス内で実行する
マネージドエージェントは運用負荷を下げるが、ランタイム料金とホスト型状態を受け入れる必要がある
SDK は制御性が高いが、インフラと監視を自社で運用する必要がある
データレジデンシーが厳しい場合は SDK が有力
非同期で長時間動く低機密ワークロードはマネージドエージェントが有力
どちらを選んでも、API と MCP サーバーの契約テストは必須
SDK でプロトタイプし、必要に応じてマネージドエージェントへ移行するのは現実的。ただし移行はプロジェクトとして扱う

次のステップは、エージェントを顧客データや本番 API に接続する前に、依存 API と MCP サーバーをテストすることです。Apidog をダウンロードして、エンドポイントのモック、契約テスト、エージェントの実リクエストデバッグを行い、選択したホスティングモデルを信頼できる依存関係の上に構築してください。

よくある質問

Claude マネージドエージェントと Claude エージェント SDK の主な違いは何ですか？

マネージドエージェントは、Anthropic がエージェントループとセッションごとのサンドボックスを実行するホスト型 REST API です。アプリはイベントを送信し、結果をストリーミングで受け取ります。

エージェント SDK は、同じようなループを自社プロセスと自社インフラ内で実行する Python または TypeScript ライブラリです。同じ Claude モデルを使えますが、運用責任の境界が違います。

Claude エージェント SDK は以前の Claude Code SDK と同じものですか？

はい。Claude Code SDK は、コーディングタスク以外のエージェント用途も含めるため、Claude エージェント SDK に名称変更されました。エージェントループ、組み込みツール、コンテキスト管理は Claude Code を支える仕組みと同じです。

どちらが安価ですか？

ワークロード次第です。

マネージドエージェントは、Claude トークン料金に加えて、アクティブセッション時間のランタイム料金が発生します。SDK には Anthropic の時間単位ランタイム料金はありませんが、自社コンピューティング、監視、スケーリング、オンコール運用のコストが発生します。

予算化する前に、Anthropic の最新料金ページを確認してください。

MCP サーバーは両方で使用できますか？

はい。どちらも Model Context Protocol を介して外部ツールを接続できます。

そのため、本番エージェントに接続する前に MCP サーバーをテストすることが重要です。Apidog を使用した MCP サーバーのテストガイドでは、MCP サーバーが公開する各ツールを直接検証する方法が説明されています。

顧客データを Anthropic のインフラストラクチャから外に保持するにはどうすればよいですか？

Claude エージェント SDK を使い、エージェントループを自社環境内で実行します。SDK の場合、ツール実行とセッション状態は自社インフラに残ります。

マネージドエージェントでは、サンドボックスとイベントログが Anthropic の環境、または条件付きで AWS 側に存在します。厳格なデータレジデンシー要件がある場合は SDK を検討してください。

Claude マネージドエージェントは本番環境に対応していますか？

2026年4月にパブリックベータとしてリリースされ、すべてのリクエストで managed-agents-2026-04-01 ベータヘッダーが必要です。

コアセッション機能は一般に API アカウントで利用可能ですが、成果物やマルチエージェントなど一部機能は研究プレビューとして別途アクセス申請が必要です。本番採用前に最新ドキュメントでステータスを確認してください。

エージェントが実際の API にアクセスする前にテストするにはどうすればよいですか？

以下を実施します。

エージェントが呼び出す API をモックする
MCP サーバーを単独でテストする
リクエストとレスポンススキーマの契約テストを作る
現実的なトラフィックをモックにリプレイする
エージェントが実際に送るリクエストを観察する

Apidog は、API モック、契約テスト、AI エージェントおよび A2A デバッガーを含めてこの流れを支援します。詳細は、API を呼び出す AI エージェントのテスト方法を参照してください。

片方から始めて、後でもう片方に切り替えることはできますか？

可能です。一般的には、Claude エージェント SDK でローカルプロトタイプを作り、その後マネージドエージェントへ移行する流れがあります。

ただし、これは設定変更ではありません。インターフェースはライブラリから REST + イベントに変わり、カスタムツール実行やセッション状態の扱いも変わります。移行プロジェクトとして計画してください。