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 など）とエージェント間の通信を保護します。
- エージェントから任意の場所への通信（下り（外向き））: Google Cloud で実行されているエージェントと、任意の場所で実行されているサーバー、ツール、API 間の通信を保護します。
この Codelab では、エージェントから任意の場所（下り）モードに焦点を当てます。
セキュリティ ポリシーを適用するために、Agent Gateway はエコシステムの他の部分と緊密に統合されています。
- エージェント レジストリ: 承認済みのエージェントとツール（サードパーティの 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 ランタイムにデプロイする
- ID ベースのアクセス（IAM）とコンテンツ スクリーニング（Model Armor）用に Agent Gateway サービス拡張機能を構成する
- エージェントの安全なエンドツーエンドの実行をトレースして検証する
必要なもの
- ウェブブラウザ（Chrome など）
- 課金が有効で、オーナー権限を持つ Google Cloud プロジェクト
- 組織レベルの IAM 権限（この Codelab では組織スコープのロールが付与されます）
- Cloud DNS に委任された制御対象のドメイン（一般公開マネージド証明書の場合）
- Terraform、
gcloud、基本的な Google Cloud ネットワーキングの知識
Codelab のトポロジ
この Codelab では、3 つの内部ツールと安全に通信するエンドツーエンドの住宅ローン審査エージェントをデプロイします。
まず、VPC や Agent Gateway として構成された内部アプリケーション ロードバランサなど、基本的なネットワーキングをプロビジョニングします。次に、3 つの Model Context Protocol（MCP）サーバーを Cloud Run にデプロイします。これらは、内部の独自のツールとして機能します。
- ドキュメント管理（
legacy-dms） - 会社のメールアドレス（
corporate-email） - 収入の確認（
income-verification）
ツールを配置したら、ADK で構築した Mortgage Assistant（mortgage-agent）を Agent ランタイムにデプロイします。このエージェントを構成して、プライベート下り（外向き）に 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 ゾーンも必要です。
プライベート ネットワーキングの概要フロー
プライベート ネットワーキング アプローチを使用するには:
- 一般公開 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
terraform apply
terraform apply は、デフォルト パスに約 40 個のリソースをプロビジョニングし、新しいプロジェクトで 8 ～ 10 分かかります（enable_cloud_run_private_networking = true の場合は約 60 個のリソース / 15 ～ 20 分）。作成されるのは次のとおりです。
- プロジェクトの基盤（API、サービス ID、割り当て）
- VPC、サブネット（プライマリ、プロキシ専用、PSC、PSC インターフェース、エージェント ゲートウェイのコロケーション）、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権限付与 - エージェント レジストリ エンドポイント（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. エージェント レジストリ エンドポイントを検査する
Agent Registry は、エージェントが実行時に検出するサービス（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 回評価されます。ここでは、呼び出し元エージェントの ID にターゲット MCP サーバーに対する
roles/iap.egressorがあるかどうかを確認する IAP を呼び出すために使用されます。 - 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 ポリシーを使用して、エージェント ゲートウェイにバインドします。
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
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 にデプロイする
エージェントの依存関係をインストールしてデプロイします。
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 \
--model-endpoint-location=global
スクリプトが完了したら、出力された reasoningEngines/ をシェルにコピーします。
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} のエージェント レジストリ内の 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 条件を適用します。エージェント ゲートウェイは、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" \
--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 コンソールで [エージェント プラットフォームのデプロイ] ページを開きます。
- ランタイム リストを絞り込む必要がある場合は、[フィルタ] フィールドを使用してから、
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
エージェントは、send_email ツールにアクセスできないことを確認し、それに応じて応答する必要があります。
エージェントは OpenTelemetry 計測でデプロイされているため、エージェントが応答するたびに切り替えることができる 4 つのサイドパネル ビューが Playground に表示されます。
- トレース - Agent Gateway、IAP REQUEST_AUTHZ、Model Armor CONTENT_AUTHZ スパンを含む会話の完全なトレース
- イベント - 現在のターンの呼び出されたツールとイベントの詳細のグラフ
- State - エージェントのセッション状態とツールの入力/出力
- セッション - このランタイムに対して開始したすべてのセッション
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
プレイグラウンドに戻って、会話をもう一度試します。
- Google Cloud コンソールで [エージェント プラットフォームのデプロイ] ページを開きます。
- ランタイム リストを絞り込む必要がある場合は、[フィルタ] フィールドを使用してから、
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 アプリを選択します。
- [Your Gemini Enterprise webapp is ready] セクションに表示されている 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. トラブルシューティングと一般的な解決策
terraform applyがエージェント ゲートウェイで「リソースが作成中のため更新できません」というエラーで失敗する - ゲートウェイのテナント プロジェクトが落ち着くまで約 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 LB への 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を編集していないことを確認します。
18. クリーンアップ
推論エンジンは 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
19. 完了
おめでとうございます！Agent Gateway を使用して、マルチツール ADK エージェントの包括的なエージェント ガバナンスを正常に実装しました。エージェント ゲートウェイは、一元化されたネットワーク コントロール プレーンとして機能することで、プライベート ツールへの安全な下り（外向き）パスを確立し、Identity-Aware Proxy を介してきめ細かい ID ベースの IAM ポリシーを適用し、統合された Model Armor ガードレールを使用してコンテンツのやり取りをサニタイズすることを可能にしました。
学習した内容
- Agent-to-Anywhere の下り（外向き）トラフィックの中央ガバナンス レイヤとして Agent Gateway をデプロイして構成する方法。
- ガバナンスされた動的ランタイム ツール検出のために Agent Registry を統合する方法。
- ツールごとおよび条件ベースの IAM ポリシーを作成して適用し、エージェントの実行パスを厳密に制御する方法。
- Agent Gateway サービス拡張機能を利用して Model Armor ポリシーを適用し、機密性の高いエージェント トラフィックを自動的にインターセプトして編集する方法。