Gemini Enterprise Agent Platform の Agent Gateway を使用したエージェント ワークロードの管理

1. はじめに

Gemini Enterprise Agent Platform は、データにグラウンディングされたエンタープライズ グレードの AI エージェントを構築、スケーリング、管理、最適化するためのオープン プラットフォームです。

Agent Runtime は、オープンソースの Agent Development Kit（ADK）で構築されたエージェントなど、Google Cloud 内で安全に実行するためのマネージド実行環境を提供します。

この Codelab では、これらのコア ビルディング ブロックを使用して、Gemini Enterprise でユーザーが開始したエージェントが内部ツールに安全にアクセスする方法を説明します。

Agent Gateway について

Agent Gateway は、プラットフォームの Agent Governance スイートのネットワーキング コンポーネントです。すべてのエージェント インタラクションのネットワーク エントリ ポイントとエグジット ポイントとして機能するため、セキュリティ管理者は、デベロッパーが複雑なネットワーキング プリミティブを管理する必要なく、一元化されたガバナンスを適用できます。

これにより、主に次の 2 つのガバナンス アクセスパスが実現します。

  • クライアントからエージェント（上り（内向き））: 外部クライアント（Cursor や Gemini CLI など）とエージェント間の通信を保護します。
  • エージェントから Anywhere（下り（外向き））: Google Cloud で実行されているエージェントと、任意の場所で実行されているサーバー、ツール、API 間の通信を保護します。

この Codelab では、エージェントから任意の場所（下り）モードに焦点を当てます。

Agent Gateway によるアクセス制御

セキュリティ ポリシーを適用するために、Agent Gateway はエコシステムの他の部分と緊密に統合されています。

  • Agent Registry: 承認されたエージェントとツール（サードパーティの MCP サーバーを含む）の一元的なライブラリ。
  • エージェント ID: すべてのエージェントに一意の追跡可能なペルソナ。エンドツーエンドの mTLS で自動的に保護されます。
  • Identity-Aware Proxy（IAP）と IAM: 特定のツールへの呼び出しを許可する前に、エージェントの ID をきめ細かい IAM 権限に対して検証するデフォルトの適用レイヤ。
  • Model Armor: Service Extensions を通じて統合された AI セキュリティ ガードレール。コンテンツをサニタイズし、プロンプト インジェクション攻撃やデータ漏洩から保護します。

デプロイモード（Cloud Run のパブリック ネットワーキングとプライベート ネットワーキング）

この Codelab を利用できるようにするには、Cloud Run にデプロイされた内部ツール（MCP サーバー）の 2 つのネットワーキング パスから選択できます。

  1. デフォルト（パブリック上り（内向き））: MCP サーバーは、パブリック ホスト名（ingress=all）を使用して Cloud Run にデプロイされます。トラフィックは、標準の *.run.app URL を介してエージェントからツールにルーティングされます。これにはカスタム DNS ドメインは必要ありません。ガバナンスのコンセプトを学ぶにはこれが最も速い方法です。
  2. 安全（プライベート ネットワーキング）: オプションの完全プライベート アーキテクチャ。MCP サーバーは制限され（ingress=internal-and-cloud-load-balancing）、サーバーレス NEG を使用する内部アプリケーション ロードバランサを介して公開されます。これには、Google マネージド証明書をプロビジョニングするためのパブリック DNS ドメインを所有している必要があります。

Terraform の構成時に、優先パスを選択します。

Cloud Run のネットワーク エンドポイント上り（内向き）の詳細については、ドキュメントをご覧ください。

演習内容

  • Terraform を使用してコア インフラストラクチャ スタックをプロビジョニングする
  • 内部ツールを Cloud Run の MCP サーバーとして構築してデプロイする
  • PSC インターフェースの下り（外向き）を使用して ADK エージェントを Agent Runtime にデプロイする
  • ID ベースのアクセス（IAM）とコンテンツ スクリーニング（Model Armor）用に Agent Gateway サービス拡張機能を構成する
  • エージェントの安全なエンドツーエンドの実行をトレースして検証する

必要なもの

  • ウェブブラウザ（Chrome など）
  • 課金が有効で、オーナー権限を持つ Google Cloud プロジェクト
  • 組織レベルの IAM 権限（この Codelab では組織スコープのロールが付与されます）
  • Cloud DNS に委任された制御対象のドメイン（一般公開マネージド証明書の場合）
  • Terraform、gcloud、基本的な Google Cloud ネットワーキングの知識

Codelab のトポロジ

エンドツーエンドのアーキテクチャ: Gemini Enterprise から Agent Runtime、Agent Gateway、Cloud Run の MCP サーバーまで

この Codelab では、3 つの内部ツールと安全に通信するエンドツーエンドの住宅ローン審査エージェントをデプロイします。

まず、VPC や、Agent Gateway として構成された内部アプリケーション ロードバランサなど、基本的なネットワーキングをプロビジョニングします。次に、3 つの Model Context Protocol（MCP）サーバーを Cloud Run にデプロイします。これらは、内部の所有するツールとして機能します。

  • ドキュメント管理（legacy-dms）
  • 会社のメールアドレス（corporate-email）
  • 収入の確認（income-verification）

ツールを準備したら、ADK で構築した Mortgage Assistant（mortgage-agent）を Agent Runtime にデプロイします。このエージェントを構成して、プライベート下り（外向き）に PSC インターフェースを使用し、エージェント レジストリを介してランタイム ツールの検出を有効にします。

フローを保護するには、2 つのサービス拡張機能を使用してエージェント ゲートウェイを構成します。まず、REQUEST_AUTHZ 拡張機能がツールごとの IAM ポリシーに対してエージェント ID を検証し、エージェントが承認されたツールにのみアクセスできるようにします。次に、Model Armor を使用する CONTENT_AUTHZ 拡張機能が、エージェントのプロンプトとレスポンスをスクリーニングします。

最後に、Gemini Enterprise にエージェントを登録し、エンドユーザーとして住宅ローンの審査タスクをトリガーして、Cloud Trace を使用して安全でガバナンスされた実行を確認します。

この Codelab は、あらゆるレベルのプラットフォーム エンジニアとセキュリティ エンジニアを対象としています。完了までに 100 分ほどかかります。

2. 始める前に

プロジェクトを作成して認証する

課金が有効になっている新しい GCP プロジェクトを作成（または再利用）し、Cloud Shell またはローカルマシンを認証します。

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

ブートストラップ API を有効にする

Terraform の基盤モジュールでは、最初の適用で約 30 個の API が有効になりますが、terraform init と GCS 状態バケットには小さなブートストラップ セットが必要です。

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

必要なツールをインストールする

ツールチェーンをインストールします。Cloud Shell では、これらのほとんどがすでに存在しています。ワークステーションの場合:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

また、Terraform >= 1.12.2、Python 3.12 以降、Google Cloud SDK（gcloud）も必要です。

環境変数を設定する

この Codelab の残りの部分では、これらがシェルにエクスポートされていることを前提としています。

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

すべての変数が正しく入力されていることを確認します。3 つの値が返されるはずです。

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

組織 ID が自動入力されない場合は、手動で検索して設定できます。

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. リポジトリのクローンを作成する 

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

デモ ディレクトリの内容の概要は次のとおりです。

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Terraform 状態バケットとバックエンド構成を作成する

リモート状態を保持する GCS バケットを作成し、バックエンド テンプレートをコピーします。

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

terraform/backend.conf を実際の値で編集します。

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5. （省略可）一般公開 Cloud DNS ゾーンを作成する

このラボでは、デフォルトで Cloud Run の上り（内向き）構成が all に設定され、エージェント レジストリは各 MCP サーバーをパブリック *.run.app URL に登録します。追加の DNS、証明書、ロードバランサは必要ありません。プライベート ネットワーキング（内部アプリケーション LB の背後にある ingress = internal-and-cloud-load-balancing を使用した Cloud Run）に切り替える場合は、Certificate Manager が LB 証明書を検証できるように、パブリック Cloud DNS ゾーンも必要です。

プライベート ネットワーキングの概要

プライベート ネットワーキング オプションの概要

プライベート ネットワーキング アプローチを使用するには:

  1. 一般公開 Cloud DNS ゾーンを作成します。Certificate Manager は、CNAME を書き込むことでリージョン マネージド証明書を検証します。
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

mcp.${DOMAIN_NAME} の対応するプライベート ゾーン（MCP 内部 LB と Agent Runtime からの DNS ピアリングで使用）は、Terraform によって自動的に作成されます。手動で作成する必要はありません。プライベート ネットワーキングがオフの場合、パブリック ゾーンもプライベート ゾーンもプロビジョニングされません。

6. Terraform 変数を構成する

tfvars の例をコピーして編集します。

cp terraform/example.tfvars terraform/terraform.tfvars

enable_cloud_run_private_networking によってゲートされる 2 つのデモパスがあります。

デフォルト パス: パブリック上り（内向き）の Cloud Run

最もシンプルな設定: デフォルトのパスでは、terraform.tfvars の 3 つの値のみを編集する必要があります。ファイル内の他のすべての変数には、デモに適したデフォルト値がすでに設定されています。

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

プライベート ネットワーキング（省略可）

enable_cloud_run_private_networking = true を設定し、次の変数を追加して、完全なセキュア スタックをプロビジョニングします。

  • 内部アプリケーション LB
  • Google マネージド証明書
  • ingress = internal-and-cloud-load-balancing を使用した Cloud Run
  • Agent Gateway DNS ピアリング。
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. Terraform を使用してインフラストラクチャをデプロイする

初期化、確認、適用:

cd terraform
terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply tfplan

terraform apply は、デフォルト パスに約 40 個のリソースをプロビジョニングし、新しいプロジェクトで 8 ～ 10 分かかります（enable_cloud_run_private_networking = true の場合は約 60 個のリソース / 15 ～ 20 分）。作成されるのは次のとおりです。

  • プロジェクトの基盤（API、サービス ID、割り当て）
  • VPC、サブネット（プライマリ、プロキシ専用、PSC、PSC インターフェース、Agent Gateway のコロケーション）、Cloud NAT、ファイアウォール ルール
  • Cloud Run イメージの Artifact Registry リポジトリ
  • 3 つの Cloud Run サービス + サービスごとのランタイム SA（上り（内向き）はデフォルトで all、プライベート ネットワーキングが有効な場合は internal-and-cloud-load-balancing）
  • Model Armor テンプレート + IAM
  • Agent Gateway、PSC-I ネットワーク アタッチメント、IAP と Model Armor の拡張機能、両方の認可ポリシー、プロジェクト レベルの roles/iap.egressor 権限付与
  • Agent Registry エンドポイント（Vertex AI、IAP、Discovery Engine など）と 3 つの MCP サーバー（デフォルトでは *.run.app/mcp に登録。プライベート ネットワーキングが有効な場合は ./mcp に登録）

enable_cloud_run_private_networking = true の場合のみ:

  • サーバーレス NEG（URL マスク ルーティング）とプライベート DNS A レコードを備えた内部リージョン アプリケーション LB
  • VPC にアタッチされた MCP プライベート DNS ゾーン（mcp..）
  • パブリック DNS ゾーン モジュール（Certificate Manager DNS 認証）+ リージョン Google マネージド証明書
  • PSC インターフェース DNS ゾーン（解決するプライベート ホスト名がない場合は孤立するため、マスター フラグでもゲートされます）
  • mcp.. の Agent Gateway DNS ピアリング（自動的に付加）

8. エージェント レジストリ エンドポイントを検査する

エージェント レジストリは、エージェントが実行時に検出するサービス（Google API と独自の MCP サーバー）のプロジェクトごとのカタログです。住宅ローン エージェントは起動時にこれを読み取り、ツールを動的にバインドします。MCP URL はエージェント コードやデプロイ コマンドに組み込まれていません。

エンドポイント

Terraform がユーザーに代わって実行した内容 - agent_registry_google_apis の各 Google API に対して、5 つのバリアント（グローバル、mTLS グローバル、リージョン、リージョン mTLS、リージョン REP）を登録しました。たとえば、aiplatform の場合は次のようになります。

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION