1. はじめに
Gemini Enterprise Agent Platform は、データにグラウンディングされたエンタープライズ グレードの AI エージェントを構築、スケーリング、管理、最適化するためのオープン プラットフォームです。
Agent Runtime は、Google Cloud 内で安全にエージェント（オープンソースの Agent Development Kit（ADK）で構築されたエージェントなど）を実行するためのマネージド実行環境を提供します。
この Codelab では、これらのコア ビルディング ブロックを使用して、Gemini Enterprise でユーザーが開始したエージェントが内部ツールに安全にアクセスする方法を説明します。
Agent Gateway について
Agent Gateway は、プラットフォームの Agent Governance スイートのネットワーキング コンポーネントです。すべてのエージェント インタラクションのネットワーク エントリ ポイントとエグジット ポイントとして機能するため、セキュリティ管理者は、デベロッパーが複雑なネットワーキング プリミティブを管理する必要なく、一元化されたガバナンスを適用できます。
これにより、主に次の 2 つのガバナンス アクセスパスが実現します。
- クライアントからエージェント（上り（内向き））: 外部クライアント（Cursor や Gemini CLI など）とエージェント間の通信を保護します。
- エージェントから Anywhere（下り（外向き））: Google Cloud で実行されているエージェントと、任意の場所で実行されているサーバー、ツール、API 間の通信を保護します。
この Codelab では、エージェントから任意の場所（下り）モードに焦点を当てます。
セキュリティ ポリシーを適用するために、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 つのネットワーキング パスから選択できます。
- デフォルト（パブリック上り（内向き））: MCP サーバーは、パブリック ホスト名（
ingress=all）を使用して Cloud Run にデプロイされます。トラフィックは、標準の*.run.appURL を介してエージェントからツールにルーティングされます。これにはカスタム DNS ドメインは必要ありません。ガバナンスのコンセプトを学ぶにはこれが最も速い方法です。 - 安全（プライベート ネットワーキング）: オプションの完全プライベート アーキテクチャ。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 のトポロジ
この Codelab では、3 つの内部ツールと安全に通信するエンドツーエンドの住宅ローン審査エージェントをデプロイします。
まず、VPC やエージェント ゲートウェイとして構成された内部アプリケーション ロードバランサなど、基盤となるネットワーキングをプロビジョニングします。次に、3 つの Model Context Protocol（MCP）サーバーを Cloud Run にデプロイします。これらは、内部の独自のツールとして機能します。
- ドキュメント管理（
legacy-dms） - 会社のメールアドレス（
corporate-email） - 収入の確認（
income-verification）
ツールを準備したら、ADK で構築した Mortgage Assistant（mortgage-agent）を Agent Runtime にデプロイします。このエージェントを構成して、プライベート下り（外向き）に PSC インターフェースを使用し、エージェント レジストリを介してランタイム ツールの検出を有効にします。
フローを保護するには、2 つのサービス拡張機能を使用して Agent Gateway を構成します。まず、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 ゾーンも必要になります。
プライベート ネットワーキングの概要
プライベート ネットワーキング アプローチを使用するには:
- 一般公開 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}-rep \
--project=${PROJECT_ID} --location=${REGION} \
--display-name="Vertex AI Platform Regional (REP)" \
--endpoint-spec-type=no-spec \
--interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"
MCP サーバー
Terraform は 3 つの MCP サーバーも登録します。他の MCP サーバーを登録するには、ドキュメントの手順に沿って操作します。
gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC
登録されたエンドポイントと MCP サーバーを確認します。
gcloud alpha agent-registry services list \
--project=${PROJECT_ID} --location=${REGION} \
--format="value(displayName,name)"
gcloud alpha agent-registry mcp-servers list \
--project=${PROJECT_ID} --location=${REGION} \
--format="value(displayName,name)"
情報提供元: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl
9. Agent Gateway の構成を確認する
Agent Gateway は、Agent Runtime とツール間の Google 管理のガバナンス プレーンです。AGENT_TO_ANYWHERE モードでは、プロジェクトの Agent Registry にバインドされ、お客様所有の PSC インターフェースを介して下り（外向き）が行われるため、VPC 内のプライベート MCP サーバーにアクセスできます。
このゲートウェイを手動でインポートする場合、YAML は次のようになります。
# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
governedAccessPath: AGENT_TO_ANYWHERE
registries:
- "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
egress:
networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
dnsPeeringConfig:
domains:
- mcp.${DOMAIN_NAME}.
targetProject: ${PROJECT_ID}
targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc
gcloud alpha network-services agent-gateways import agent-gateway \
--source=agent-gateway.yaml \
--location=${REGION}
ゲートウェイが Terraform によって作成されたことを確認します。
gcloud alpha network-services agent-gateways describe agent-gateway \
--location=${REGION}
10. IAP と Model Armor の認可を調べる
Agent Gateway は認可をサービス拡張機能に委任します。デモでは 2 つのポリシー プロファイルを使用します。
- REQUEST_AUTHZ - ヘッダー ステージでリクエストごとに 1 回評価されます。ここでは、IAP を呼び出すために使用されます。これにより、呼び出し元エージェントの ID にターゲット MCP サーバーに対する
roles/iap.egressorがあるかどうかが確認されます。 - CONTENT_AUTHZ - コンテンツのサニタイズのために、本文イベントを拡張機能にストリーミングします。ここでは、Model Armor を呼び出すために使用されます。これは、Sensitive Data Protection（SDP）を介して、プロンプト インジェクション、ジェイルブレイク、RAI 違反、（必要に応じて）PII をスクリーニングします。
IAP REQUEST_AUTHZ 拡張機能
cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF
gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
--source=iap-authz-extension.yaml \
--location=${REGION} \
--project=${PROJECT_ID}
REQUEST_AUTHZ ポリシーを使用して、Agent Gateway にバインドします。
curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
-d '{
"name": "agent-gateway-iap-policy",
"policyProfile": "REQUEST_AUTHZ",
"action": "CUSTOM",
"target": {
"resources": [
"projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
]
},
"customProvider": {
"authzExtension": {
"resources": [
"projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
]
}
}
}'
Model Armor の CONTENT_AUTHZ 拡張機能
拡張機能の metadata.model_armor_settings には、Model Armor が各コールアウトの評価に使用するリクエスト テンプレート ID とレスポンス テンプレート ID が含まれています。
cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
model_armor_settings: '[
{
"request_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
"response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
}
]'
EOF
gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
--source=ma-extension.yaml \
--location=${REGION} \
--project=${PROJECT_ID}
curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
-d '{
"name": "agent-gateway-ma-policy",
"policyProfile": "CONTENT_AUTHZ",
"action": "CUSTOM",
"target": {
"resources": [
"projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
]
},
"customProvider": {
"authzExtension": {
"resources": [
"projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
]
}
}
}'
カスタム DLP テンプレート
Model Armor の sdpSettings.basicConfig は、組み込みの infoType リストを使用します。より細かく制御する（カスタム情報タイプ、部分マスキング、代理置換、可能性による秘匿化）には、sdpSettings.advancedConfig を介して独自の Cloud DLP 検査テンプレートと匿名化テンプレートを Model Armor に指定します。
POSSIBLE 以上の可能性で米国社会保障番号を検出する検査テンプレートを作成します。
curl -fsS -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: ${PROJECT_ID}" \
"https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
-d '{
"templateId": "agw-ssn-inspect-template",
"inspectTemplate": {
"displayName": "SSN Inspect Template",
"inspectConfig": {
"infoTypes": [
{ "name": "US_SOCIAL_SECURITY_NUMBER" }
],
"minLikelihood": "POSSIBLE"
}
}
}'
各検出結果を情報型トークン（[US_SOCIAL_SECURITY_NUMBER] など）に置き換える匿名化テンプレートを作成します。
curl -fsS -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: ${PROJECT_ID}" \
"https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
-d '{
"templateId": "agw-ssn-redaction-template",
"deidentifyTemplate": {
"displayName": "SSN Redaction Template",
"deidentifyConfig": {
"infoTypeTransformations": {
"transformations": [{
"primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
}]
}
}
}
}'
次に、sdpSettings.advancedConfig を介して Model Armor テンプレートのレスポンス構成をペアに指定します（Terraform の model_armor モジュールが advanced_config を設定する場所です）。
{
"filterConfig": {
"sdpSettings": {
"advancedConfig": {
"inspectTemplate": "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
"deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
}
}
}
}
IAP エグレッサー IAM（MCP サーバーごと）
Terraform は、暗黙的な IAP エージェント レジストリにプロジェクト全体の roles/iap.egressor バインディングを作成しません。IAP REQUEST_AUTHZ が実際に評価するバインディングは、MCP サーバーごと、推論エンジンごとです。エージェントがデプロイされ、エージェント ID がわかった後に付与されます。「エージェントに MCP サーバーごとの下り（外向き）を付与する」ステップでは、そのために scripts/grant_agent_mcp_egress.sh が実行されます。
11. MCP サーバーをビルドして Cloud Run にデプロイする
cloudrun/*.yaml.tmpl ファイルと skaffold.yaml.tmpl ファイルは、${PROJECT_ID}、${REGION}、${MCP_INGRESS}（Cloud Run 上り（内向き）アノテーション）を参照します。Terraform 出力から MCP_INGRESS を取得して、レンダリングされたマニフェストが enable_cloud_run_private_networking と同期するようにし、envsubst でレンダリングします。
Cloud Run 上り（内向き）構成をエクスポートします。
allinternal-and-cloud-load-balancing（プライベート ネットワーキング アプローチを使用する場合）
export MCP_INGRESS=all
ルートのデモ ディレクトリに戻ります。
cd ..
テンプレートの値を置き換えます。
envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done
各 Cloud Run サービスは、サービスごとのランタイム SA Terraform（mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com など）として実行されます。これらの SA としてデプロイするには、自分自身に roles/iam.serviceAccountUser が必要です。
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="user:$(gcloud config get-value account)" \
--role="roles/iam.serviceAccountUser"
Cloud Build でビルドし、Skaffold でデプロイします。
skaffold run
Skaffold は、3 つのイメージ（legacy-dms、corporate-email、income-verification-api）を Artifact Registry リポジトリにビルドし、新しいダイジェストを指すように各 Cloud Run サービスを更新します。
確認:
gcloud run services list --region=${REGION}
3 つのサービスすべてが ACTIVE ステータスになっていることを確認します。
12. 住宅ローン エージェントを Agent Runtime にデプロイする
レジストリに登録したすべてのエンドポイントに対する IAP Egressor ロールをすべてのエージェントに付与します。エージェントはこれらのエンドポイントにアクセスする必要があります。これは、エージェントのデプロイ時に、パッケージの github.com にアクセスし、デプロイに必要なさまざまな Google API にアクセスする必要があるためです。
./scripts/grant_agent_mcp_egress.sh --bind-all-agents --endpoints
エージェントの依存関係をインストールしてデプロイします。
cd src/mortgage-agent
uv sync
uv run python deploy_agent.py \
--project=${PROJECT_ID} \
--region=${REGION} \
--enable-agent-identity \
--agent-name=mortgage-agent \
--agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
--mcp-invoker-sa=$(terraform -chdir=../../terraform output -raw agent_mcp_invoker_email) \
--model-endpoint-location=global
スクリプトが完了したら、出力された reasoningEngines/ をシェルにコピーします（例: 4262292559201566720）。
export AGENT_ID=<numeric-id-from-output>
cd ../..
13. エージェントに MCP サーバーごとの下り（外向き）を付与する
IAP REQUEST_AUTHZ 拡張機能は、呼び出し元の 特定の MCP サーバーまたはエンドポイントでエージェントの roles/iap.egressor を確認して、各ツール呼び出しを承認します。エージェントから MCP サーバーへの下り（外向き）ポリシーを作成するをご覧ください。
スクリプト（scripts/grant_agent_mcp_egress.sh）は、projects/${PROJECT_ID}/locations/${REGION} の Agent Registry で MCP サーバーを列挙し、エージェント プリンシパルの roles/iap.egressor バインディングを各サーバーの IAM ポリシーに統合します（gcloud add-iam-policy-binding セマンティクスをミラーリングします）。
ユースケース 1 - 特定の MCP サーバーにスコープ設定された無条件付与
./scripts/grant_agent_mcp_egress.sh \
--mcp \
--agent-id ${AGENT_ID} \
--mcp-filter "legacy-dms income-verification"
ユースケース 2 - 特定の MCP サーバーにスコープ設定された条件付き付与（CEL）
エージェントを単一の MCP サーバー上のツールのサブセットに制限するには、IAM 条件を適用します。Agent Gateway は、IAP REQUEST_AUTHZ が CEL に公開するツールごとの属性（以下を含む）を公開します。
iap.googleapis.com/mcp.toolNameiap.googleapis.com/mcp.tool.isReadOnlyiap.googleapis.com/request.auth.type。
corporate-email でエージェントを読み取り専用ツールのみに制限します。
./scripts/grant_agent_mcp_egress.sh \
--mcp \
--agent-id ${AGENT_ID} \
--mcp-filter "corporate-email" \
--condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true || api.getAttribute('iap.googleapis.com/mcp.toolName', '') == ''" \
--condition-title "ReadOnlyToolsOnly" \
--condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"
この実行後、corporate-email の書き込みツールは IAP REQUEST_AUTHZ から 403 PermissionDenied を返します。読み取り専用ツールは引き続き動作します。
バインディングを確認する
[ポリシー] タブに移動すると、エンドポイントと Mcp サーバーに対して作成されたポリシーのリストが表示されます。
その他のユースケース:
すべての MCP サーバーで、1 つのエージェントにスコープ設定された無条件の権限付与
これは、エージェントを再デプロイするたびに実行します。フィルタと条件がない場合、名前付きエージェントはレジストリ内のすべての MCP サーバーで roles/iap.egressor を取得します。
./scripts/grant_agent_mcp_egress.sh \
--mcp \
--agent-id ${AGENT_ID}
14. Agent Platform コンソールでエージェントをテストする
Agent Platform コンソールには、デプロイされたエージェントと直接チャットできる Playground が付属しています。これは、エージェントを Gemini Enterprise に接続する前に、ツール呼び出しの簡易テストを行い、トレースを検査する最も迅速な方法です。
- Google Cloud コンソールで [Agent Platform Deployments] ページを開きます。
- ランタイム リストを絞り込む必要がある場合は、[フィルタ] フィールドを使用してから、
mortgage-agentランタイムをクリックします。 - [Playground] タブを開きます。
- プロンプトを入力してエージェントとチャットします。
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?
これにより、ドキュメント管理ツールと収入確認ツールからレスポンスが返されます。このレスポンスでは、SSN も編集されます。5. もっと聞くプロンプトを入力します。
Can you send a summary of this to my email jane@example.com
IAP 拡張機能がドライラン モードになっているため、条件付きポリシーは適用されず、エージェントはメールを正常に送信できます。
エージェントは OpenTelemetry 計測でデプロイされているため、エージェントが応答するたびに切り替えることができる 4 つのサイドパネル ビューが Playground に表示されます。
- トレース - Agent Gateway、IAP REQUEST_AUTHZ、Model Armor CONTENT_AUTHZ スパンを含む、会話の完全なトレース
- イベント - 現在のターンの呼び出されたツールとイベントの詳細のグラフ
- 状態 - エージェントのセッション状態とツールの入力/出力
- セッション - このランタイムに対して開始したすべてのセッション
15. IAP 認証を適用する
デプロイを検証したので、IAP 適用モードを null に更新してポリシーを適用できます。terraform.tfvars を開き、モードを DRY_RUN から null に更新します。
# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = null
変更を適用します。
terraform apply
Playground に戻って、会話をもう一度試します。
- Google Cloud コンソールで [Agent Platform Deployments] ページを開きます。
- ランタイム リストを絞り込む必要がある場合は、[フィルタ] フィールドを使用してから、
mortgage-agentランタイムをクリックします。 - [Playground] タブを開きます。
- プロンプトを入力してエージェントとチャットします。
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?
これにより、ドキュメント管理ツールと収入確認ツールからレスポンスが返されます。このレスポンスでは、SSN も編集されます。5. もっと聞くプロンプトを入力します。
Can you send a summary of this to my email jane@example.com
すべてが正しく設定されている場合、エージェントは承認ポリシーによりメールを送信できないと回答する必要があります。
16. Gemini Enterprise の設定とテスト
Gemini Enterprise を設定する
Gemini Enterprise の利用を開始するガイドに沿って操作します。
ADK エージェントを Gemini Enterprise に登録する
Gemini Enterprise にエージェントを登録する手順は、こちらをご覧ください。
- Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。
- エージェントが登録されている Gemini Enterprise アプリ を選択します。
- [Gemini Enterprise ウェブアプリの準備ができました] セクションに表示されている URL を開きます。
- 左側のメニューから [エージェント] タブを選択して、Agent Galleryを開きます。
- [Mortgage Assistant Agent] を選択して、チャットを開始します。
Agent Runtime Playground で同じプロンプトを試します。
最初のプロンプト:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?
もっと聞くプロンプト:
Can you send a summary of this to my email jane@example.com
コンソールの [エージェントのデプロイ] セクションに戻り、エージェントのデプロイを選択して [トレース] タブに移動すると、Gemini Enterprise から発信された呼び出しを示すスパンに Gemini アシスタント エージェントが表示されます。
17. オブザーバビリティ ダッシュボード
認可デバッグ ダッシュボードには、Agent Runtime エージェントの下り（外向き）トラフィックの単一ビューが表示されます。
ダッシュボードには次のものが表示されます。
- エージェント ➔ エンドポイント（403 拒否）
- エージェント ➔ MCP サーバー（403 エラー）
- エージェント ➔ エージェント（403 拒否）
- 未登録のアウトバウンド ブロック
- トラフィックの概要と IAP 強制モード
- GCP API IAM 拒否
各ウィジェットには、エージェント ID、リクエストされたホスト、登録されたリソースパス、Gateway と IAP がリクエストを承認したかどうかが表示されます。
- 未登録のアウトバウンド ブロック - このウィジェットは、宛先ホスト名がエージェント レジストリに存在しないため、Agent Gateway がブロックしたトラフィックを分離します。ゲートウェイ プロキシはこれらのリクエストが IAP に到達する前にブロックするため、これらのエントリの IAP 監査ログはありません。
- トラフィックの概要と IAP 適用モード - すべてのトラフィック パターンを示す表を表示するウィジェットです。重要なのは、IAP ドライランのステータスが含まれていることです。これにより、IAP ポリシーがトラフィックを積極的にブロックしているのか、単に監視しているのかを確認できます。
- GCP API IAM 拒否 - このウィジェットは、標準の Cloud Audit Logs（
cloudaudit.googleapis.com）を検索して、エージェントの基盤となる Google Cloud API 権限エラーを検出します。
このダッシュボードは、Cloud コンソールで確認できます。Monitoring > Dashboards > Agent Platform: Authorization Debugging
18. トラブルシューティングと一般的な解決策
Gemini CLI を使用した AI 支援デバッグ
Gemini CLI 内の agent-platform-debugger スキルを使用して、問題をトラブルシューティングできます。スキル パッケージは、AI を活用したデバッグのための専門知識をパッケージ化したものです。Gemini CLI は、ワークスペース スコープで .agents/skills/ を .gemini/skills/ のファーストクラス エイリアスとして扱うため、スキルを直接使用できます。Codelab Repo 内からこのスキルを使用するには:
リポジトリ ディレクトリに移動して、Gemini CLI を起動します。
cd /path/to/cloud-networking-solutions/demos/agent-gateway
gemini
プロンプトが表示されたらワークスペースを信頼します（ワークスペース スコープのスキルは信頼できるフォルダからのみ読み込まれます）。スキルが読み込まれたことを確認します。
/skills list
リストに agent-platform-debugger が表示されます。表示されない場合は、スキルを再読み込みします。
/skills reload
トラブルシューティングのヒント
terraform applyが Agent Gateway で「リソースが作成中のため更新できません」というエラーで失敗する - 認可ポリシーをアタッチする前に、Agent Gateway のテナント プロジェクトが安定するまでに約 30 秒かかります。モジュールのtime_sleep.wait_for_gatewayがこれを処理します。terraform applyを再実行するだけです。- エージェントが「MCP サーバーが見つかりません」と報告するか、ユーティリティ ツールのみで起動する -
terraform.tfvarsでenable_agent_registry_endpoints = trueを確認し、次の操作を行います。gcloud alpha agent-registry mcp-servers list \ --project=${PROJECT_ID} --location=${REGION} - ツール呼び出しで 403 PermissionDenied が返される -
scripts/grant_agent_mcp_egress.shを再実行します。最も一般的な原因は、エージェントの再デプロイ後に再付与を忘れることです（reasoningEngines/はデプロイごとに変更されます）。 skaffold runが「サービス アカウントの権限が拒否されました」というエラーで失敗する -roles/iam.serviceAccountUserがありません。前の手順で自己付与を再実行します。- Agent Gateway から MCP ロードバランサへの DNS ピアリング エラー -
agent_gateway_dns_peering_config.target_networkがprojects/${PROJECT_ID}/global/networks/${VPC_NAME}と完全に一致し、すべてのdomainsエントリが末尾のドットで終わっていることを確認します。 terraform planが Cloud Run イメージタグの更新を繰り返す -lifecycle { ignore_changes }ルールにより、これは発生しません。発生した場合は、skaffold runの後にterraform.tfvarsでmcp_services[*].imageを編集していないことを確認します。
19. クリーンアップ
推論エンジンは Terraform によって管理されません（ADK SDK によって作成されます）。手動で削除します。
gcloud beta ai reasoning-engines delete ${AGENT_ID} \
--region=${REGION} --project=${PROJECT_ID}
Terraform で作成したものをすべて削除します。
cd terraform
terraform destroy
cd ..
この Codelab 専用に一般公開 DNS ゾーンを作成した場合:
gcloud dns managed-zones delete agw-example-com
最後に、Terraform 状態バケットを削除します。
gcloud storage rm -r gs://${PROJECT_ID}-tfstate
20. 完了
おめでとうございます！Agent Gateway を使用して、マルチツール ADK エージェントの包括的なエージェント ガバナンスを正常に実装しました。Agent Gateway は、一元化されたネットワーク コントロール プレーンとして機能することで、プライベート ツールへの安全な下り（外向き）パスを確立し、Identity-Aware Proxy を介してきめ細かい ID ベースの IAM ポリシーを適用し、統合された Model Armor ガードレールを使用してコンテンツのやり取りをサニタイズすることを可能にしました。
学習した内容
- Agent-to-Anywhere の下り（外向き）トラフィックの中央ガバナンス レイヤとして Agent Gateway をデプロイして構成する方法。
- ガバナンスされた動的ランタイム ツール検出のために Agent Registry を統合する方法。
- ツールごとおよび条件ベースの IAM ポリシーを作成して適用し、エージェントの実行パスを厳密に制御する方法。
- Agent Gateway サービス拡張機能を利用して Model Armor ポリシーを適用し、機密性の高いエージェント トラフィックを自動的にインターセプトして編集する方法。