メインコンテンツへ移動
AIチュートリアル

AI Agent GatewayでAIエージェントをデプロイして安全に保護する

Docker Composeを使ったAI Agent Gatewayのデプロイ、管理者の初期設定、3つのサービスプレーンの検証、MCPツールの接続、分析機能の有効化、外部アクセスの制御、認証情報の保護、さらに高度なエージェントおよびLLMワークフローに向けたゲートウェイの準備方法を学びます。

約18分で読了
AI Agent GatewayでAIエージェントをデプロイして安全に保護する

AIエージェントゲートウェイとは？

AIエージェントゲートウェイは、AIエージェントとエージェントが呼び出すシステムの間に配置されるオープンソースサービスです。MCPツールサーバーと、Anthropic Claude、AWS Bedrock、OpenAI、Geminiなどの対応LLMプロバイダーに対して、認証済みで可観測性を備えた単一のエントリーポイントを提供します。

各エージェントにツールの認証情報やプロバイダー設定をコピーする代わりに、認証、シークレット、アクセス ポリシー、リクエストログを一元管理できます。ゲートウェイは単一のバイナリとして配布され、組み込みの管理コンソールを備えています。

このサービスは3つのリスナーを公開します。

  • ポート8080のMCPプレーン：エージェントからMCPリクエストを受け取り、許可された操作を登録済みのツールサーバーに転送します。
  • ポート8081のコントロールプレーン：REST APIと管理コンソールを提供します。
  • ポート8082のLLMプレーン：対応するLLMリクエストをプロキシし、使用状況を記録します。

PostgreSQLが必要です。Redis互換のセッションストアはオプションで、MCPプレーンを複数のレプリカで実行できるようにします。バンドル版のデプロイではValkeyを使用します。ClickHouseはオプションで、追加の分析機能を提供します。

主な機能

  • すべてのリクエストを認証：ゲートウェイが発行するAPIキーは、テナントとロールにスコープ設定されます。
  • コネクター認証情報を保護：認証情報は暗号化されたシークレットストアに保存され、呼び出し元に公開されることなく、送信MCPリクエストに注入されます。
  • エージェント固有のツールポリシー：プロファイルで、エージェントが使用できるツールを制限できます。制限はツール一覧の取得時だけでなく、tools/callの実行時にも適用されます。
  • プロンプトとリソース：ゲートウェイはバックエンドのプロンプトとリソースを共有名前空間経由で転送し、同じプロファイルポリシーを適用します。
  • スキルとコマンド：プロファイルには、ネイティブMCPメカニズムを通じて公開される再利用可能な参照テキストとプロンプトテンプレートを含められます。
  • マルチプロバイダーLLMプロキシ：LLMプレーンはAnthropic、Bedrock、OpenAI、Geminiに対応し、トークン使用量と推定コストを記録します。
  • 一元化された可観測性：必要なストレージを有効にすると、コンソールからアクセスログ、LLMログ、セッションタイムライン、分析ダッシュボードを利用できます。
  • 送信リクエストの保護：サーバーサイドリクエストフォージェリのリスクを低減するため、内部、ループバック、リンクローカル、その他のプライベート宛先はデフォルトでブロックされます。

前提条件

最も迅速なセットアップにはDocker Composeを使用します。開始前に、以下をインストールまたは確認してください。

  • Docker Composeプラグインを備えたDocker（Docker Desktop、Colima、Docker Engineなど）。
  • ヘルスチェック用のcurlと、APIレスポンス処理用のjq。
  • 空いているローカルポート8080、8081、8082。
  • 分析プロファイルとそのAdminerサービスを有効にする場合は、ポート8090。
  • 少なくとも4 GBの空きDocker容量。ClickHouse分析を追加する場合は8 GB。

macOSとLinuxに対応しています。WindowsはWSL2経由で使用できますが、現在この環境はテストされていません。

Docker外でビルドする場合、リポジトリにはGo 1.27、コンソール用のNode.js 26、makeが必要です。一部の実行例では、さらにnpx、Python、kind、kubectl、またはプロバイダーのAPIキーが必要です。

ゲートウェイのインストールと起動

1. リポジトリをクローンする

git clone https://github.com/Tuskira/ai-agent-gateway.git
cd ai-agent-gateway

2. 標準のComposeスタックを起動する

docker compose -f deploy/docker-compose.yml up --build -d

Dockerが必要なコンポーネントをビルドまたはダウンロードし、データベースを初期化するため、初回起動には時間がかかる場合があります。

3. コントロールプレーンを待つ

until curl -sf localhost:8081/api/v1/health >/dev/null; do sleep 1; done

このループは、コントロールプレーンのヘルスエンドポイントが正常なレスポンスを返すまで待機します。

4. 3つのプレーンすべてを確認する

curl localhost:8080/health
curl localhost:8081/api/v1/health
curl localhost:8082/health

正常なレスポンスが返れば、MCP、コントロール、LLMの各リスナーが利用可能であることを確認できます。

管理アクセスを初期化する

新しいデプロイメントにはコンソールユーザーもAPIキーもありません。まず、デフォルトテナントと管理者APIキーを作成します。

docker compose -f deploy/docker-compose.yml exec gateway /gateway bootstrap-key

このコマンドはAPIキーを一度だけ表示します。コネクターの登録や管理API操作を行うためのスタートガイドのワークフローで使用するため、安全に保存してください。

次に、最初のコンソールユーザーを作成します。

docker compose -f deploy/docker-compose.yml exec gateway /gateway create-user -tenant default -username admin -role admin

このコマンドは一度だけ使用できる一時パスワードを表示します。http://localhost:8081を開き、adminとしてサインインし、表示されたら一時パスワードを変更してください。

通常、プログラムはAPIキーで認証します。緊急時のフォールバックとして、コンソールでAPIキーを使用することもできます。

基本的な使い方：MCPサーバーを追加して呼び出す

ゲートウェイの用語では、MCPツールサーバーはAPI上ではコネクター、コンソール上ではMCPです。サインイン後、MCP → カタログを開くと、追加可能な既製のMCPサーバーを確認できます。

通常、最初に行うワークフローは次のとおりです。

  1. 管理者 API キーを作成して保存します。
  2. MCP サーバーをコネクターとして登録します。
  3. コネクターに必要な認証情報を設定します。
  4. エージェントプロファイルを作成または選択します。
  5. コネクターのツールをそのプロファイルで利用できるようにします。
  6. ポート 8080 のゲートウェイ MCP リスナー経由で、許可されたツールを呼び出します。
  7. 管理コンソールで呼び出しを確認します。

リポジトリには、examples/01-quickstart に実行可能な完全なウォークスルーが含まれています。スタックを起動し、3つすべてのプレーンを検証し、管理者キーを初期設定し、サンプル MCP サーバーを登録して、そのツールの1つを呼び出します。コネクターの正確な登録方法とツール呼び出しリクエストについては、スタートガイドに従ってください。

外部認証情報を必要としないすべての例を実行するには、次を使用します。

make examples-smoke

エージェントプロファイルによるアクセス制御

プロファイルでは、エージェントが利用できるツール、プロンプト、リソース、スキル、コマンドを定義します。ツールの制限は、エージェントが tools/call を呼び出した時点で検証されるため、tools/list からツールを非表示にすることだけが唯一の適用手段ではありません。

より強力にポリシーを適用するには、API キーをプロファイルにバインドします。バインドがない場合、呼び出し元は X-Agent-Profile-Name ヘッダーで使用するプロファイルを指定できます。キーとプロファイルのバインドにより、呼び出し元が別のプロファイルを自由に選択することを防げます。

複数の MCP サーバーがプロンプトやリソースを公開している場合、ゲートウェイはそれらを共通の名前空間で管理します。プロンプトにはコネクター名が付加され、リソースにはゲートウェイが管理する URI が使用されます。どのエントリにエージェントがアクセスできるかは、同じプロファイルルールによって決まります。

LLM プロキシの使用

LLM プレーンは、対応するモデルプロバイダー（Anthropic、AWS Bedrock、OpenAI、Gemini）への一元化された経路を提供します。これにより、エージェントアプリケーションはツールに使用するものと同じ制御された経路を通じてモデルのトラフィックを送信できます。

プロキシ経由の各呼び出しについて、ゲートウェイはトークン使用量を記録し、コストを見積もることができます。プロバイダーの設定、自分のキーの使用、Bedrock の認証情報モード、ルート、キャプチャ設定、コストの動作については、LLM プレーンガイドに記載されています。

クライアントを設定する前に、ヘルスエンドポイントを使用してリスナーを検証します。

curl localhost:8082/health

アナリティクスの有効化

標準デプロイでは、ClickHouse なしで LLM ログをサポートします。概要ダッシュボード、アクセスログ、セッションタイムライン、ClickHouse ベースのアナリティクスを追加するには、analytics プロファイルを指定して Compose を起動します。

GATEWAY_SINKS_CLICKHOUSE_ENABLED=true docker compose -f deploy/docker-compose.yml --profile analytics up --build -d

この設定にはより多くのローカルリソースが必要で、ポート 8090 を使用する場合があります。

機密性の高いリクエスト本文の保護

デモ用スタックは、LLM のリクエスト本文とレスポンス本文を PostgreSQL に保存し、それぞれ 1 MiB を上限とします。アナリティクスプロファイルでは、LLM と MCP のリクエスト本文およびレスポンス本文も ClickHouse に保存し、コンソールに表示できるようにします。これらの本文がコンテナログに出力されることはありません。

プロンプト、モデルのレスポンス、ツールのペイロードに機密情報が含まれる可能性がある場合は、本文の保存を完全に無効にしてください。

GATEWAY_LLM_PROXY_CAPTURE_STORE_BODIES=false GATEWAY_CAPTURE_STORE_BODIES=false docker compose -f deploy/docker-compose.yml up --build -d

本番データでキャプチャ機能を使用する前に、オブザーバビリティのドキュメントを確認してください。

ローカルまたはプライベート MCP サーバーへの安全な接続

ゲートウェイは、デフォルトでループバック、プライベート、リンクローカル、その他の内部宛先をブロックします。また、クラウドのメタデータアドレス 169.254.169.254 も常にブロックします。このポリシーにより、コネクター、カタログエントリ、モデルターゲットが、ホストやネットワーク上の機密サービスに気付かないうちにアクセスすることを防ぎます。

作成時にホスト名がブロック対象のアドレスにしか解決されない場合、ゲートウェイは 400 egress_blocked を返して拒否します。まだ解決されないホスト名は受け入れられる場合がありますが、ゲートウェイが接続を試みる際に再度チェックされます。

バイナリを直接実行する場合

make run で実行し、同じマシン上で MCP サーバーを稼働させる場合は、ループバックを明示的に許可します。

GATEWAY_EGRESS_ALLOWED_CIDRS=127.0.0.0/8,::1/128 make run

付属の Compose スタックを使用する場合

付属の Compose 設定では、すでに host.docker.internal とループバック CIDR が許可されています。そのため、ノートパソコン上で稼働するサーバーには host.docker.internal 経由でアクセスできます。共有環境では、必要でない限りこれらの許可を削除してください。

Kubernetes またはプライベートネットワークを使用する場合

クラスター内の Kubernetes サービスでは、呼び出す DNS 名だけを許可します。例：

GATEWAY_EGRESS_ALLOWED_HOSTS=my-mcp-server.my-ns.svc

対象となる Pod またはサービスの CIDR を許可することもできます。VPN 専用またはプライベートネットワーク上のサーバーでは、すべてのプライベートアドレス範囲を有効にするのではなく、特定のホスト名または狭い CIDR を追加してください。

アウトバウンドの許可リストは、可能な限り限定してください。初期テストを簡単にするためだけに保護機能を無効にしないでください。

高度な運用のヒント

  • 人間とプログラムのアクセスを分離する：管理者にはコンソールアカウントを使用し、エージェントや自動化処理にはゲートウェイが発行するAPIキーを使用します。
  • キーをプロファイルに紐付ける：プロファイルに紐付けたキーを使用すると、呼び出し元がリクエストヘッダーでプロファイルを選択できるようにする場合よりも、強力な保証が得られます。
  • 認証情報をゲートウェイで管理する：コネクターの認証情報を一元的に設定し、エージェントに基盤となるシークレットが渡らないようにします。
  • コネクターの認証情報をローテーションする：各エージェントを個別に更新するのではなく、コネクターおよび認証情報の管理機能を使用します。
  • データの取得を制御する：機密性の高いプロンプトやツール結果を処理する前に、リクエスト本文とレスポンス本文を保持するかどうかを決定します。
  • 複数レプリカに備える：MCPプレーンを1つのレプリカを超えてスケールする場合は、オプションのRedisプロトコルセッションストアを設定します。
  • 送信先ルールを限定する：広範なプライベート範囲ではなく、個別のホストまたはCIDRを許可します。
  • 実例を参照する：個別の実例では追加のシナリオを扱っており、必要なツールやベンダーキーがある場合は、それぞれのREADMEファイルに記載されています。
  • 変更を想定する：このプロジェクトは1.0未満のアルファ版ソフトウェアであるため、APIや設定はマイナーバージョン間で変更される可能性があります。

Docker外でのビルド

ローカル開発には、Go 1.27、Node.js 26、makeをインストールします。リポジトリではmake buildとmake runのワークフローを利用できます。開発およびリリース用のオプションツールには、golangci-lint、govulncheck、goreleaserがあります。

開発規約、テストコマンド、プルリクエストのガイダンス、ストア・シンク・プロバイダーの拡張ポイントについては、コントリビューションガイドを参照してください。

まとめ

AI Agent Gatewayは、認証済みエンドポイントの背後でMCPツールと複数のLLMプロバイダーへのアクセスを一元化します。プロファイルの適用、認証情報の注入、外部ネットワーク制御、可観測性機能により、ポリシーとシークレットを個々のエージェント設定から分離できます。

Docker Composeのクイックスタートから始め、生成された管理者キーを保存し、コンソールユーザーを作成して、最初のコネクターワークフローを完了します。その後、プロファイルに紐付いたAPIキーを追加し、プロバイダーへのアクセスを設定し、適切な本文取得ポリシーを選択します。ClickHouse分析は、追加の可視性が必要な場合にのみ有効にしてください。