Claude Managed Agentsの使い方：ステップバイステップセットアップガイド

AIエージェントの構築は、単にモデルを呼び出すことにとどまりません。エージェントループの管理、ツールの実行、実行環境の提供、セッション状態の維持、権限の処理、そしてエージェントの動作の観察（オブザーバビリティ）が必要です。

Claude Managed Agentsは、こうしたインフラの大部分を代行してくれます。 自前でエージェントの実行環境を構築・運用する代わりに、エージェントを定義し、実行場所を設定し、タスクを実行するためのセッションを作成するだけで済みます。マネージド実行環境がモデル呼び出しとツール実行を処理し、アプリケーションはイベントを通じてエージェントとやり取りします。

本ガイドでは、最初のエージェントの作成と環境設定から、セッションの実行、ツールやMCPサーバーの追加、エージェントイベントのハンドリングまで、Claude Managed Agentsの使い方をステップバイステップで解説します。

まず概念的な基礎を理解したい場合は、Claude Managed Agentsの概要とアーキテクチャの仕組みについてのガイドをご覧ください。本ガイドは、すでに開発を始める準備ができている方を対象としています。

前提条件

Managed Agentを作成する前に、以下が必要です：

1. Claude Consoleアカウント
2. Anthropic APIキー
3. Anthropic SDK
4. Python、TypeScript、またはその他のサポートされている言語

ステップ 1: CLIとSDKのインストール

Pythonの場合、SDKをインストールします：

次に、APIキーを環境変数として設定します：

Anthropicは、Managed Agentリソースを管理するためのant CLIも提供しています。

SDKは環境変数からキーを自動的に読み込むため、アプリケーションコード内に直接記述する必要はありません。

Managed Agents APIの有効化

Claude Managed Agentsは、現在AnthropicのベータAPI経由で利用可能です。Managed Agentsベータは、以下のヘッダーによって識別されます：

managed-agents-2026-04-01ベータヘッダー

公式SDKを使用している場合、Managed Agents APIにアクセスすると、SDKがこのヘッダーを自動的に処理します。

基本的なクライアントのセットアップは以下のようになります：

これで、アプリケーションからManaged Agents APIを利用する準備が整いました。

次のステップでは、使用するClaudeモデル、従う指示、アクセスできるツールを定義して、エージェント自体を作成します。

ステップ 2: エージェントの定義

エージェントはMarkdownファイルで定義します。フロントマター（frontmatter）にはエージェントの設定が含まれ、本文にはシステムプロンプトが含まれます。

以下は、リポジトリからリリースノートを下書きするエージェントの例です：‍


agent_toolset_20260401ツールセットを使用すると、エージェントはシェルコマンドやファイル操作などの機能を含むAnthropicの事前構築済みツールにアクセスできるようになります。フルセットが不要な場合は、個別ツールを設定することも可能です。利用可能なオプションについては、ツールリファレンスを参照してください。

設定をrelease-notes-agent.mdとして保存し、ant CLIで適用します：

ant apply release-notes-agent.md


これによりエージェントが作成され、そのIDが返されます。

エージェントは永続的なリソースです。一度作成すれば、そのエージェントを使用するセッションを開始するたびにIDを参照するだけでよく、タスクごとにエージェントを再作成する必要はありません。

次に、エージェントセッションが実行される環境（environment）を作成します。

ステップ 3: 環境の作成

環境は、エージェントセッションが実行されるサンドボックスを定義します。

environment.yamlファイルを作成します：‍


次に、それを適用します：

ant apply environment.yaml


エージェントと環境を同時に適用することも可能です：

networking: unrestricted設定により、サンドボックスに無制限のネットワークアクセスが付与されます。内部システムや機密データを扱うエージェントの場合は、より制限されたネットワーク設定を使用してください。

これで、エージェントを実行するために必要な2つのリソースが揃いました：

• エージェント： エージェントが何であり、何ができるかを定義します。
• 環境： エージェントがどこで実行されるかを定義します。

次に、これらを接続するセッションを作成します。

ステップ 4: セッションの開始

セッションは、特定のタスクに取り組むエージェントの実行インスタンス1つを指します。

エージェントIDと環境IDを渡してセッションを作成します：

セッションIDはこの特定の実行を識別します。メッセージの送信、イベントのストリーミング、エージェントとの継続的なやり取りにこのIDを使用します。

同じエージェントで複数のセッションを実行できます。例えば、Release Notes Agentは、同じエージェント設定を維持しながら、リリースごとに個別のセッションを実行することが可能です。

ステップ 5: メッセージの送信とレスポンスのストリーミング

セッションが実行されたら、エージェントにタスクを送信します。

まずイベントストリームを開き、その後にユーザーメッセージを送信します：‍


この呼び出しの裏側では、マネージド実行環境が環境設定に基づいてサンドボックスをプロビジョニングし、エージェントループを開始し、Claudeにツールの選択と実行を行わせ、イベントをアプリケーションにストリーミング返送します。

上記の3つのイベントタイプは、通常最初に処理することになる代表的なものです：

• agent.message — エージェントが応答を送信します。
• agent.tool_use — エージェントがツールを使用します。
• session.status_idle — エージェントが現在の作業を完了しました。

ステータス変更やエラーを含む全イベントのリストについては、イベントとストリーミングのリファレンスを参照してください。

ここまでの手順で、動作するManaged Agentが完成しました：定義を行い、実行環境を与え、セッションを開始し、タスクを送信しました。

次に、実行中のエージェントを制御し、長時間のセッションをハンドリングする方法を見ていきます。

ステップ 6: 実行中のエージェントの制御

エージェントが完了するのを待たずに、進行方向を変更することができます。

user.interruptイベントを送信して現在のターンを停止し、続いて新しい指示とともにuser.messageを送信できます：

割り込み（interrupt）を行うと、モデルの現在の応答が停止し、制御がセッションに戻ります。エージェントがツール呼び出しの途中である場合、そのツールの完了を待つため割り込みの適用に時間がかかることがあります。割り込みが処理されると、セッションはidleに戻り、次のuser.messageによって新しいターンが開始されます。

これは、エージェントが誤った方向に向かっていると気づいた長時間タスクに便利です。セッションを終了してやり直す代わりに、同じセッションを再利用し、追加のコンテキストを与えて軌道修正できます。

新しい指示をすぐに送信せずに、実行中のセッションを割り込み停止することも可能です：‍


中断後もセッションは利用可能な状態に保たれるため、何が起こったかを確認した上で次に送信内容を決定できます。

次に、アプリケーションが実行中のセッションとの接続を失った場合の処理方法について説明します。

ステップ 7: 切断のハンドリングとセッションの再開

エージェントがまだ作業中であっても、ストリーミング接続が切断されることがあります。しかし、セッションや作業内容が失われたわけではありません。

Managed Agentsはセッションのイベント履歴をサーバー側に保持するため、アプリケーションはタスクを最初からやり直すことなく、同じセッションに再接続できます。

重要なのは、セッション作成時にセッションIDを保存しておくことです：‍

アプリケーションの接続が切れた場合は、同じsession_idを使用して再接続し、セッションとのやり取りを継続します。

これは長時間実行されるエージェントにおいて重要です。ブラウザタブの閉鎖、プロセスの再起動、一時的なネットワーク障害が発生しても、エージェントにタスクを最初からやり直させる必要はありません。

本番環境のアプリケーションでは、セッションIDを永続的なアプリケーション状態として扱い、メモリ内だけでなく、プロセスの再起動後も取得できる場所（データベース等）に保存してください。

イベントストリームは、アプリケーションと実行中セッションの間の接続に過ぎません。セッション自体は、その接続とは独立して存在し続けます。

次に、MCPサーバーとツールを使用してエージェントに機能を追加する方法を見ていきます。

自社インフラでの実行

デフォルトではクラウドサンドボックスが使用されますが、これが理由で導入を断念せざるを得ないチームもあります。データの居住性（データレジデンシ）やコンプライアンスの規定によりAnthropicがホストする実行環境が使えない場合でも、セルフホスト型サンドボックスを使用すれば、Anthropicがループを運用したまま、お客様が管理するインフラ上でセッションを実行できます。

移動するものと移動しないものに注意してください：実行環境はお客様のインフラに移動しますが、オーケストレーションはAnthropic側に留まります。

定期実行（スケジュールデプロイ）の設定

オンデマンドではなく定期的なサイクルで実行すべきエージェントの場合、スケジュールデプロイ機能により、cronスケジュールに基づいてセッションを実行できます。スケジューラーを自前で立てることなく、夜間の初期仕分け処理や週次レポートの生成などを実行できます。

コストをコントロールする

Claude Managed Agentsの課金は2つの軸で行われます：モデルのトークン使用量と、コンテナ時間をカバーする約$0.08/セッション時間の実行環境料金です。

事前に知っておくべき3つのポイント：

アイドル時間は無料であるため、人間からの入力待ち状態のセッションには実行環境料金が発生しません。バッチ割引はないため、通常バッチ処理するような作業でもコストは同じです。また、Web検索ツールは通常のツールセットとは別に課金されます。

通常、セッション時間あたりの料金は少額であり、トークン費用がコストの大半を占めます。1回の実行で消費されるトークン量は、設定内容というよりもハーネスがコンテキストをどう管理するかに依存します。完全なコスト構造の詳細については、Claude Managed Agentsの料金解説で分析しています。

チームが直面する限界・制限

プロトタイプが動作した後に表面化しやすい制約が2つあります。モデルがAnthropic専用であるため、利用量が増加しても安価なモデルへ切り替えることができません。また、ループはAnthropicによって運用されているため、コンテキスト管理の戦略を自ら制御することはできません。

導入を検討中で他の選択肢と比較したい場合は、Claude Managed Agentsの代替手段で業界の全容をカバーしています。

TrueForge：Claude Managed Agentsのオープンソース代替手段（最大75%コスト削減）

TrueForgeは、本番環境でのエージェントの動作をより細かく制御したいチーム向けにTrueFoundryが提供する、オープンソースでベンダーニュートラルなエージェントハーネスです。特定のモデルプロバイダーに実行環境を縛られることなく、お好みのモデル、MCPサーバー、インフラを持ち込みながら、エージェントループ、ツール実行、コンテキスト管理、承認フロー、サンドボックス環境を処理できます。

Hermesのようなセルフホスト型エージェントでは本番インフラの多くが開発者に委ねられますが、TrueForgeは複数のチームや環境にまたがってエージェントを運用するために必要なコントロールプレーンを提供します。これには、集中型のMCPアクセスとクレデンシャル管理、Human-in-the-Loop（人間の介入による承認）、サンドボックスでの実行、オブザーバビリティ、ガバナンスが含まれます。

ローカル環境ではnpx @truefoundry/trueforgeで実行でき、チーム向けにはDocker ComposeやHelmを使ってデプロイできます。

TrueForgeはまた、エージェント実行環境をモデル層から分離しています。これにより、チームはエージェント自体を再構築することなく、モデルを変更したり、ワークロードを異なるプロバイダーにルーティングしたりできます。TrueFoundryのAI Gatewayと組み合わせることで、モデルルーティングとコスト制限を適用し、高価なフロンティアモデルを必要としないタスクへの使用を避けることができます。その結果、フルマネージドの実行環境と自前ですべてのエージェントインフラを構築することの「良いとこ取り」を実現します：本番エージェントを大規模運用するために必要な運用管理機能を備えたオープンソースのエージェントハーネスです。‍

TrueFoundryがClaude Managed Agentsに対して行ったベンチマークにおいて、TrueForgeは両者をOpus 4.8で実行した際、約40%のトークン消費量でほぼ同等のタスク精度を達成し、1実行あたり約30%安価になりました。さらに、TrueForge上でGLM-5.2を使用して同じベンチマークを実行した場合、Claude Managed Agentsの1実行あたり$11.80に対して約$2.90で同等の~11/14のタスクスコアを達成し、約75%のコスト削減を実現しました。

TrueFoundryは、AI Gatewayの自動ルーティング（Auto Routing）を通じて、モデルコストを削減する第2の手段も提供します。すべてのリクエストをフロンティアモデルに送信する代わりに、自動ルーティングはリクエストの複雑さを分類し、異なるモデルティアに振り分けます。550個のプロンプトを対象としたTrueFoundryのベンチマークにおいて、Haiku、Sonnet、Opus間でルーティングを行うことで、ベースラインの品質を98%維持しながらコストを69%削減し、平均レイテンシは7.6秒から4.0秒に低下しました。本番環境に類似したトラフィックパターンでは、全体のコスト削減率は80%に達しました。

これら2つのレイヤーは、コストの方程式の異なる部分に対処します。TrueForgeはエージェント自体の実行オーバーヘッドを削減し、モデルルーティングはタスクが不要な場合に高価なモデルの使用を回避します。大規模にエージェントを運用するチームにとって、モデル単体の価格以上に、この両方の制御を持つことが重要になります。

TrueForgeはオープンソースでありMITライセンスで提供されます。一方、TrueFoundryのAI Gatewayは、個別エージェントから本番環境への移行時にチームが必要とする運用層（モデルアクセスの集約、予算管理、ガードレール、クレデンシャル管理、統一トレース）を追加します。

Claude Managed Agentsとより柔軟に設定可能なアーキテクチャを比較している場合、エージェントの実行環境だけでなくモデルの柔軟性、インフラの制御、エージェントコストの最適化が重要であれば、TrueFoundryは検討に値する選択肢です。

Claude Managed Agentsのオープンソース代替手段（最大75%削減）

TrueForgeを使用し、モデル、ツール、サンドボックスプロバイダーを自由に選択して、自社インフラ上で本番運用品質のAIエージェントを実行。

GitHubで見る

ドキュメント

Managed Agentsがカバーしないレイヤー

Managed Agentsは単一エージェントの実行環境を非常に優れた形で管理します。一方で管理しないのは「フリート（エージェント群）」の統合管理です。これはエージェントが5個ほどに増え、財務部門からコストを問われ、セキュリティ部門からクレデンシャルの承認者を問われるタイミングで直面する問題です。

エージェントハーネスはエージェントがどう動作するかを制御します。AI Gatewayはそのエージェントがモデルにどうアクセスするかを制御します。

例えば、組織はClaude Managed AgentsやTrueForgeを使用してエージェントを実行しながら、モデルリクエストをAI Gateway経由でルーティングできます。
TrueFoundryのAI Gatewayは、エージェントが行うすべてのモデルおよびMCP呼び出しの前に位置し、チームごとの予算、レート制限、ガードレール、クレデンシャル管理、統一トレースなど、集中型のモデルアクセスを適用します。これはチームが実行しているエージェントやフレームワークに関わらず機能します。単一のOpenAI互換APIを介して1,000以上のLLMをサポートし、オーバーヘッドはわずか約3〜4ms、単一のvCPUで350以上のRPSを処理するため、ボトネックになることなく長時間実行エージェントのホットパスに配置できます。自社VPC、オンプレミス、またはエアギャップ環境で動作します。

これは、組織が単一のモデルプロバイダーに依存するのではなく、複数のモデルにわたってエージェントを実行する場合に特に有用です。

エージェント実行環境（Runtime）： エージェントループ、ツール、状態、実行を管理します。

AI Gateway： モデルへのアクセス、ルーティング、ポリシー、オブザーバビリティ、プロバイダーの抽象化を管理します。

この分離により、チームはエージェント自体を再設計することなく、モデルの変更や追加を行えるようになります。

FAQ

Q: Claude Managed Agentsはどのように使いますか？

A: ant CLIとAnthropic SDKをインストールし、Markdownファイル内にモデル、システムプロンプト、ツールを含むエージェントを定義し、サンドボックス用にYAMLで環境を宣言し、両方を参照するセッションを作成してそのイベントをストリーミングします。エージェントと環境は一度作成すれば再利用でき、セッションはタスクごとに作成します。全体の手順は約10分で完了します。

Q: ant CLIは必須ですか？それともSDKだけで全操作が可能ですか？

A: CLIは便宜上のツールであり、必須ではありません。AnthropicはPython、TypeScript、Java、Go、C#、Ruby、PHPにおけるすべてのステップについて、cURLおよびネイティブSDKでの手順をクイックスタートで公開しています。CLIが提供する追加機能はant applyやclaude-lock.jsonであり、設定ファイルへの直貼りではなく、コードとともにエージェントおよび環境のIDをバージョン管理できるようにします。

Q: Claude Managed Agentsは自社のインフラ上で実行できますか？

A: 部分的に可能です。セルフホスト型サンドボックスを使用すると、お客様が管理するインフラ上でセッションを実行できるため、通常はデータ居住性の要件を満たすのに十分です。ただし、オーケストレーション層はAnthropic側に留まるため、スタック全体を完全に自前で実行することとは異なります。

Q: 既存のオブザーバビリティスタックと統合できますか？

A: TrueFoundryのゲートウェイ層はOpenTelemetryに準拠しており、Grafana、Datadog、Prometheusなど、既存の運用ツールに接続して、プロンプトからツールやモデルの実行に至るまで各リクエストを追跡できます。これは、異なるフレームワークのエージェントを1箇所で可視化したい場合に重要です。

Q: 多数のエージェントが存在する場合、モデルやMCPサーバーをどのようにガバナンスすればよいですか？

A: チームごとのAPIキー管理が限界に達した段階で、ゲートウェイを導入します。TrueFoundryのAI Gatewayは、単一のOpenAI互換APIの裏側に1,000以上のLLMを配置し、わずか3〜4msの遅延追加と単一vCPUで350+ RPSの性能を備え、RBAC、予算、ガードレール、クレデンシャルローテーションを提供します。Claude Managed Agents、LangGraph、その他何で構築されたエージェントであっても同様にガバナンスを適用できます。

関連ドキュメント

• Claude Managed Agentsとは？：上記のステップの背景にあるアーキテクチャ
• Claude Managed Agentsの料金解説：具体的な計算例を含む完全なコスト分析
• Claude Agent SDK vs Claude Managed Agents：本番環境でどちらを採用すべきか
• Claude Managed Agentsの代替手段：導入検討における競合・選択肢の比較
• エージェントハーネスのベストプラクティス：どのハーネスを選んでも適用できる10のルール

まとめ

Claude Managed Agentsの使い方を理解することは、主に4つのオブジェクトとそれらを作成する順序（エージェント、環境、セッション、イベント）を把握することです。セットアップ自体は極めて迅速です。時間をかけるべき価値があるのは、クイックスタートで割愛されがちな部分、すなわち切断処理、環境のネットワーク設定、そしてコストのどの部分を自力でコントロールできるかの把握です。

セットアップの速度よりも、モデルの選択肢やコンテキスト戦略が重要になる段階に達したなら、それはオープンハーネスの導入を検討すべきサインです。npx @truefoundry/trueforgeを使用すれば約1分でローカル実行できます。実際のワークロードでの動作を確認したい場合は、ウォークスルーの予約をご利用ください。