Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Agent Runtime から VPC ネットワークへの Agent Gateway 下り（外向き）

1. はじめに

この Codelab では、プライベート VPC ネットワークを介してリモートエンドポイントにアクセスする AI エージェントの Agent Gateway の下り（外向き）ガバナンスについて説明します。下り（外向き）（エージェントから任意の場所へ）モードで動作するエージェントゲートウェイは、Private Service Connect（PSC）インターフェースを使用した VPC ネットワークへのプライベート接続をサポートしています。このシナリオでは、Agent Runtime は Agent Gateway を使用して、VPC ネットワーク内の Google API の Private Service Connect（PSC）エンドポイントを使用して Cloud Run でホストされているリモートのストリーミング可能な HTTP MCP サーバーにアクセスします。

スタンドアロンのチャットボットからマルチエージェントワークフローを備えた自律型システムまで、AI アプリは外部ツールを動的に呼び出すことができます。安全で生産性の高いエージェントを実現するには、データベースのクエリ、ウェブコンテンツの取得、アクションの実行に対する制御されたアクセスをエージェントに提供することが不可欠です。ただし、企業環境では、エージェントツールの実行を保護することが課題となります。エージェントがネットワークに直接アクセスできる場合、プロンプトインジェクション攻撃やモデルのハルシネーションにより、エージェントが機密データを流出させたり、破壊的なコマンドを実行したりする可能性があります。

自律型エージェントを大規模に管理するために、Agent Gateway は Agent Platform アーキテクチャに直接統合された、一元化されたゼロトラスト適用ポイントを提供します。Agent Gateway は、各アプリケーションまたはエージェントコードに固有のカスタム実装に依存するのではなく、プラットフォームレベルで適用されるネットワークルーティング、エージェントガバナンス、ランタイムセキュリティを提供します。

Agent Gateway が下り（外向き）（agent-to-anywhere）モードで動作している場合、ゲートウェイを使用するように構成されたエージェントからのすべての送信リクエストをプロキシします。各エージェントワークロードリクエストは、一意のエージェント ID を使用して認証され、Identity-Aware Proxy（IAP）ポリシーを使用して認可されます。MCP ツールの呼び出しは動的にデコードされ、ポリシーの適用について検査されます。セキュリティ管理者は、きめ細かい権限を一元的に適用して、エージェントが承認済みのエンドポイントとメソッドのみを呼び出せるようにすることができます。

構築内容

外向き（agent-to-anywhere）モードの Agent Gateway
Identity-Aware Proxy（IAP）認可拡張機能
エージェント ID を持つ Agent Runtime ADK エージェント
Cloud Run ストリーミング可能な HTTP MCP サーバー
Google API とカスタム MCP エンドポイントを含む Agent Registry
IAM アクセス制御による認可ポリシー
VPC ネットワークリソース、Cloud DNS ゾーン、Google API 用 PSC エンドポイント
Agent Gateway 下り（外向き）の PSC ネットワークアタッチメント
Cloud Next Generation Firewall（NGFW）ファイアウォールポリシールール

図 1. Codelab アーキテクチャ

学習内容

構造化された構成シーケンスで Agent Gateway をデプロイする方法
プライベート VPC ネットワーク接続で Agent Gateway を構成する方法
認可ポリシーをドライランモードから適用モードに移行する方法
Google API エンドポイントと MCP サーバーを Agent Registry に登録する方法
エージェントゲートウェイのログを監査して下り（外向き）ガバナンスを検証する方法
Cloud NGFW ログを使用してエージェントゲートウェイの下り（外向き）トラフィックを検証する方法

必要なもの

課金を有効にした Google Cloud プロジェクト
ネットワーキングサービス、BigQuery データセット、Agent Platform リソースをプロビジョニングする IAM 権限
Google Cloud CLI（gcloud コンポーネントと bq コンポーネント）がインストールされた POSIX 互換シェル（bash または zsh）
コマンドラインツール: git、curl、jq（JSON プロセッサ）、Python 3、uv（Python パッケージマネージャー）

2. コンセプト

デプロイシーケンス

この Codelab では、構造化された構成シーケンスに従って、エージェントが初期化時に必要なリソースにアクセスできるようにし、適用されたアクセスポリシーを適用する前に接続を確認できるようにします。

この Codelab では、次のデプロイシーケンスを使用します。

DRY_RUNモードで開始: エージェントリクエストがゲートウェイに正常に到達し、通過していることを確認します（監査専用モード）。
すべてのサービスを登録する: エージェントレジストリにすべてのエージェントコンポーネントを登録し、エージェントツールのアクセス権を確認します。Cloud Logging と Agent Gateway のオブザーバビリティダッシュボードを使用して、Agent Registry へのクエリを表示します。
認可ポリシーを作成する: エージェントから MCP サーバーとエンドポイントへの下り（外向き）トラフィックを許可する認可ポリシーを作成して適用します。
ENFORCEDモードに切り替えます: 認証拡張機能ポリシーを更新して、ポリシーを適用し、承認されていない下り（外向き）トラフィックをブロックします。

図 2. デプロイシーケンス

下り（外向き）ルーティングトポロジ

Agent Gateway の下り（外向き）（agent-to-anywhere）は、エージェントワークロードの一元化されたゼロトラストアウトバウンドプロキシとして機能します。エージェントが外部ツールまたは API にリクエストを行うと、送信リクエストはエージェントゲートウェイによってインターセプトされ、ガバナンスポリシーに対して評価されてから、宛先にルーティングされます。Google Cloud Agent Platform アーキテクチャでは、Agent Gateway は次のものにデータプレーン接続を提供します。

プライベートネットワーク（VPC）: プライベート VPC 内でホストされている内部エンタープライズ API、マイクロサービス、データベース、ハイブリッド接続を介してアクセス可能なオンプレミスまたはクロスクラウドネットワークをターゲットとするアウトバウンドトラフィック。
外部ネットワーク（インターネット）: サードパーティのウェブサービス、SaaS API、パブリックエンドポイントをターゲットとするアウトバウンドトラフィック。
AI サービスとエージェントプラットフォーム: 管理対象の Google Cloud API、基盤モデル、Google MCP エンドポイント（BigQuery など）、プラットフォームガバナンスサービス（エージェントレジストリと IAP ポリシー）を対象とするアウトバウンドトラフィック。

図 3. Agent Gateway の下り（外向き）ルーティングトポロジ

この Codelab では、VPC ネットワークにデプロイされた Google API 用の PSC エンドポイントをターゲットとする Agent Runtime のカスタムエージェントからのアウトバウンドトラフィックに焦点を当てます。このアーキテクチャでは、エージェントゲートウェイの下り（外向き）に PSC ネットワークアタッチメントを使用して、Cloud Run でホストされている MCP サーバーへのプライベートアクセスを有効にします。

VPC 接続

エージェントゲートウェイの下り（外向き）（agent-to-anywhere）は、デプロイ YAML 構成ファイルで networkConfig: egress: networkAttachment: [URI] を指定することで、VPC ネットワークに接続できます。この設定では、プライベート IP アドレスに解決されるトラフィックを PSC ネットワークアタッチメント経由で VPC ネットワークに送信するルーティングルールがエージェントゲートウェイに構成されます。

図 4. エージェントゲートウェイの VPC 接続

エージェントゲートウェイは、Cloud DNS ピアリングを使用して、指定されたターゲットプロジェクトと VPC ネットワークに限定公開 DNS ホスト名を解決できます。dnsPeeringConfig: domains: [NAME] 構成にリストされている限定公開ゾーンは、ターゲットプロジェクトの Cloud DNS レコードを使用します。その他の DNS クエリは、デフォルトの VPC Cloud DNS パブリックリゾルバを使用します。

これでコンセプトの説明は終わりです。次は セットアップ セクションに進みます。

3. セットアップ

必要な IAM のロール

この Codelab でリソースを作成するには、次のロールが必要です。

カテゴリ	必要な IAM ロール（ID）	説明
API 管理	`roles/serviceusage.serviceUsageAdmin`	Google Cloud API サービスを有効にする
ネットワーキングとゲートウェイ	`roles/networkservices.admin`	Agent Gateway をプロビジョニングする
Service Extensions	`roles/serviceextensions.admin`	ルーティング拡張機能を構成する
ネットワークセキュリティ	`roles/networksecurity.admin`	認可ポリシーをデプロイする
Agent Registry	`roles/agentregistry.admin`	カタログで許可されたホスト
Vertex AI とエージェント	`roles/aiplatform.admin`	Agent Runtime ワークロードをデプロイする
外向きポリシー	`roles/iap.admin`	`roles/iap.egressor` ポリシーを適用する
Cloud Storage	`roles/storage.admin`	デプロイステージングバケットを管理する
ログと監査	`roles/logging.viewer`	トレースと監査ログを検査する
Cloud Run デベロッパー	`roles/run.developer`	Cloud Run サービスをデプロイする
Artifact Registry 読み取り	`roles/artifactregistry.reader`	コンテナイメージを pull する
Compute ネットワーク管理者	`roles/compute.networkAdmin`	VPC ネットワーキングリソースを管理する
DNS 管理者	`roles/dns.admin`	Cloud DNS のゾーンとレコードを管理する

または、roles/admin などの広範な基本ロールや、以前のロール roles/owner を使用します。

プロジェクトにアクセスする

この Codelab では、1 つの Google Cloud プロジェクトを使用します。構成手順では、gcloud CLI と Linux シェルコマンドを使用します。

まず、Google Cloud プロジェクトのコマンドラインにアクセスします。

shell.cloud.google.com の Cloud Shell
gcloud CLI がインストールされているローカルターミナル

プロジェクト ID を設定する

gcloud config set project SET_YOUR_PROJECT_ID_HERE

セッションを認証する

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

シェル環境変数を設定する

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

`gcloud cli` を更新（推奨）

Google Cloud SDK のセルフマネージドインストール（Cloud Shell の外部）を実行している場合は、コンポーネントを最新バージョンに更新します。

# update gcloud cli
gcloud components update

API サービスを有効にする

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

これでセットアップは完了です。次は [ネットワーク] セクションに進みます。

4. ネットワーク

VPC ネットワークは、カスタムモードを使用してデプロイされ、Agent Gateway と Cloud Run ダイレクト VPC 下り（外向き）の PSC ネットワークアタッチメントをサポートする標準サブネットが作成されます。

Google APIs の PSC エンドポイントは、単一の /32グローバル内部 IPv4 アドレスを使用してデプロイされ、Cloud Run へのプライベート内部アクセスをサポートします。この IP アドレスは、リージョンサブネットから割り当てられません。

ネットワークを作成する

グローバル VPC ネットワークを作成します。

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Agent Gateway PSC ネットワークアタッチメントと Cloud Run 直接 VPC 下り（外向き）のサブネットを作成します。

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

ファイアウォールルールの作成

ロギングが有効になっているすべての下り（外向き）トラフィックを許可するファイアウォールポリシーとルールを作成します。これは、Agent Gateway から VPC ネットワークに送信されるトラフィックをモニタリングするために使用されます。

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

PSC ネットワークアタッチメントを作成する

新しいプロデューサー接続を自動的に受け入れるように構成された PSC ネットワークアタッチメントを作成します。

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

PSC ネットワークアタッチメントを確認する

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

PSC エンドポイントを作成する

グローバル PSC エンドポイントの IP アドレス予約を作成します。ここで使用するアドレスは、既存のサブネットから取得したり、既存のサブネットと重複したりすることはできません。

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

all-apis バンドルを使用して Google API の PSC エンドポイントを作成します。このバンドルには Cloud Run（run.app）が含まれています。

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

PSC エンドポイントを確認する

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

DNS ゾーンとレコードを作成する

run.app ドメインの限定公開 Cloud DNS マネージドゾーンを作成します。

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

*.run.app. のワイルドカード DNS A レコードを作成し、PSC エンドポイントの IP アドレスを指すようにします。

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

DNS クエリロギングを有効にする Cloud DNS ポリシーを作成します。

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Cloud NAT を作成する

Cloud Router と Cloud NAT を作成して、MCP サーバーが VPC ネットワーク経由で外部の天気データにアクセスできるように Cloud Run ダイレクト VPC 下り（外向き）をサポートします。

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

これでネットワーク部分の説明は終わりです。次は Gateway セクションに進みます。

5. ゲートウェイ

アクセス制御を適用する前に、エージェントゲートウェイをデプロイし、認可拡張機能を DRY_RUN モードで構成します。これにより、監査目的で評価結果をロギングしながら、アウトバウンドツール呼び出しを成功させることができます。

ここで、Agent Gateway はリージョン レジストリを使用してリージョン Agent Runtime リソースをサポートし、VPC ネットワーク PSC ネットワークアタッチメントと DNS ピアリング構成の networkConfig フィールドを指定します。

ゲートウェイを作成

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

ゲートウェイを確認する

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

受け入れられた接続エンドポイントがあることを確認します。

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

これでゲートウェイの説明は終わりです。次は認可セクションに進みます。

6. 承認

Identity-Aware Proxy（IAP）のエージェントゲートウェイ認可拡張機能は、すべてのエージェントプラットフォーム通信の認可決定を委任するために使用されるサービス拡張機能の一種です。

委任フロー: エージェントが外部エンドポイントまたは MCP サーバーを呼び出そうとすると、リクエストはエージェントゲートウェイに転送されます。ゲートウェイは、アクセスをローカルで評価する代わりに、認可拡張機能を使用して IAP 評価サービスにコールアウトを送信します。IAP は、エージェントレジストリ内のターゲットリソースの IAM ポリシーに対して、エージェント（SPIFFE ベース）の ID を評価します。IAP は ALLOW または DENY の決定をゲートウェイに返します。ゲートウェイは、トラフィックを転送するか、HTTP 403 Forbidden ステータスコードでブロックします。
適用モード: DRY_RUN モードでは、IAP はリクエストを評価し、トラフィックをブロックせずに Cloud Logging に決定を記録します。ENFORCE モードでは、承認されていないエージェントからのリクエストや、登録されていないターゲットへのリクエストは直ちにブロックされます。
バインディングレイヤ: サービス拡張機能は、REQUEST_AUTHZ プロファイルで構成された認可ポリシーを使用して Agent Gateway に接続されます。

認可拡張機能

認可拡張機能は、接続設定と、サービスがどのように動作し、Agent Gateway と統合されるかを定義するその他のパラメータを含むセキュリティプロバイダサービスを指定します。

認可拡張機能を作成する

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

認可拡張機能をインポートする

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

認可拡張機能を確認する

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

認可ポリシー

認可ポリシーは、セキュリティプロバイダ（IAP）をターゲット Gateway リソースにバインドし、インターセプトプロファイル（REQUEST_AUTHZ）を指定します。

認可ポリシーを作成する

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

認可ポリシーをバインドする

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

認可ポリシーを検証する

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

これで認可に関する説明は終わりです。次は Codebase セクションに進みます。

7. コードベース

この Codelab で使用するエージェント、MCP サーバー、エンドポイント登録コードは、リモートの Google Cloud GitHub リポジトリで管理されています。次の手順では、リポジトリをローカルに複製し、必要なファイルを現在の作業ディレクトリ構造にコピーしてから、一時ファイルをクリーンアップします。

Agent Runtime がパッケージ化されたエージェントアプリケーションコードとその依存関係アーティファクトをアップロード、ビルド、デプロイするために、ストレージステージングバケットが作成されます。

リモートアーティファクトを取得する

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

ステージングバケットを作成する

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

これでコードベースの説明は終わりです。次は Registry セクションに進みます。

8. レジストリ

Agent Registry は、AI エコシステム内のすべてのエージェント、MCP サーバー、エンドポイント（API）の一元化されたインベントリです。また、AI アプリケーションで使用するために登録された他のツールやサービスを一覧表示、検索、検出するために使用できるカタログでもあります。Agent Gateway は、レジストリのデータモデルをガバナンスフレームワークとして使用して、下り（外向き）アクセス制御を適用します。プリンシパル呼び出しエージェントの IAM ロール付与は、レジストリリソースにバインドされたポリシーに対してチェックされます。

環境をブートストラップし、さまざまな Google API とサービスを使用してエージェントをサポートするために、このラボに必要なコア API インターフェースをバンドルする単一のレジストリエンドポイントサービスを作成します。これにより、ほとんどのエージェントが使用する一般的なツールセットのガバナンスポリシーを簡単に管理できるようになります。

エンドポイントの登録

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

エンドポイントの登録を確認する

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

レジストリに関する説明は以上です。次は MCP サーバーのセクションに進みます。

9. MCP サーバー

デプロイの IAM 権限を付与する

ソースコードから Cloud Run サービスをデプロイできるように、デフォルトのコンピューティングサービスアカウントに権限を付与します。

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

IAM 権限を確認する

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

MCP サーバーをデプロイする

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

上り（内向き）の IAM 権限を付与する

ユーザーアクセスのポリシーをバインドする

Cloud Run ホスト型 MCP サーバーを呼び出すための権限をユーザーアカウント（自分自身）に付与します。これは、toolspec 生成スクリプトの実行に必要です。

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

IAM 権限を確認する

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

MCP 呼び出し用のカスタム SA を作成する

Cloud Run ホスト型 MCP サーバーを呼び出すカスタムサービスアカウントを作成します。このサービスアカウントは、Cloud Run にアクセスするための有効な Google 署名付き OIDC ID トークンを取得するためにエージェントによって使用されます。

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

サービスアカウントのポリシーをバインドする

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

IAM 権限を確認する

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

認証用の IAM 権限を付与する

デフォルトの Compute サービスアカウントにサービスアカウントの権限借用ロールを付与します。これにより、アプリケーションのデフォルト認証情報（ADC）で実行されているエージェントは、カスタム呼び出し元サービスアカウントに代わって Google 署名付き OIDC ID トークンを生成し、Cloud Run への呼び出しを認証できます。

認証のバインドポリシー

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

IAM 権限を確認する

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

MCP `toolspec` を作成する

MCP サーバーを手動で登録する場合は、ツール仕様ファイルを含める必要があります。toolspec.json ファイルには、MCP サーバーで使用可能になったすべてのツールが一覧表示され、登録後に他のユーザーが検出できるようになります。

mcp-weather/ コードベースに含まれている test_mcp.py スクリプトは、ターゲット MCP サーバーに接続（SSE または HTTP 経由）し、list_tools() を呼び出して、サーバーによって公開されている利用可能なすべてのツールを取得することで、toolspec.json ファイルを生成します。

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

生成された toolspec 出力を確認すると、下り（外向き）ポリシーの評価と適用に Agent Gateway が使用できる MCP 属性が表示されます。

MCP `toolspec` を検証する

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Cloud Run 上り（内向き）を更新する

Cloud Run サービスの上り（内向き）設定を変更して、VPC ネットワークからの上り（内向き）リクエストのみを受け入れるようにします。これにより、MCP エンドポイントへの直接のパブリックアクセスが防止され、内部リソースのみがアクセスできるようになります。VPC ネットワーク内の Google API の PSC エンドポイント宛てのトラフィックは、内部上り（内向き）と見なされ、許可されます。

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Cloud Run の上り（内向き）を確認する

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

MCP サーバーを登録する

toolspec を取得したら、MCP サーバーをリージョン Agent Registry に登録します。

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

MCP 登録を確認する

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

MCP サーバーのセクションは以上です。次は ADK エージェントのセクションに進みます。

10. ADK エージェント

Agent Runtime にデプロイされた agent-weather ADK エージェントは、Agent Platform と統合するために、デプロイスクリプトで次の設定で構成されます。

"identity_type": types.IdentityType.AGENT_IDENTITY: エージェントに一意の SPIFFE ベースのプリンシパル ID をプロビジョニングします。
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }: すべてのアウトバウンドエージェント開始トラフィックを Agent Gateway に転送して、ポリシーの評価と適用を行う

エージェントは、OIDC ID トークンを取得するための URL とサービスアカウントを渡すことで、MCP サーバーを使用するように構成されています。

エージェントをデプロイする

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

デプロイメントを確認する

デプロイのバイタルを取得する

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

レジストリエントリを確認する

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

ゲートウェイ構成を確認する

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

認証用の IAM 権限を付与する

エージェント ID を使用するようにエージェントが構成されている場合、連携 Security Token Service（STS）から sts.googleapis.com（SPIFFE ID プロバイダ）によって署名されたトークン（JWT-SVID 形式）を受け取ります。

ただし、組み込みの Cloud Run IAM 起動元チェックは、メインの Google OIDC 発行者（accounts.google.com）によって署名された標準の OIDC ID トークンのみを信頼し、検証できます。

そのため、カスタムサービスアカウントは、エージェント ID によって取得されたフェデレーション STS トークン（JWT-SVID）を、実行時にサービスアカウントの権限借用を使用して取得された標準の Google（OIDC）トークンと交換するために使用されます。

カスタムサービスアカウントに必要なロールバインディングを作成します。

認証（権限借用）のポリシーをバインドする

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

IAM 権限を確認する

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

ランタイムの IAM 権限を付与する

ランタイムの IAM 権限を付与すると、エージェントは SPIFFE ベースのプリンシパルエージェント ID を使用して、AI Platform サービスや他のコア Google API とサービスにアクセスできます。これらのポリシーは、リソース レベルで IAM を使用して適用されます。

エージェント ID に必要なロールバインディングを作成します。

エージェントアクセスのバインドポリシー

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

IAM 権限を確認する

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

これで ADK エージェントの説明は終わりです。次は ポリシーのセクションに進みます。

11. ポリシー

エージェントガバナンス認証ポリシーにより、AI エージェントからエージェントゲートウェイを経由して最終的なリソース宛先（データ取得用のプライベート MCP サーバーエンドポイントなど）にトラフィックをルーティングできます。トラフィックが宛先に到達すると、通常のサービスレベルまたはアプリケーションレベルの権限によってデータアクセスが承認されます。

エージェントゲートウェイの下り（外向き）に IAM ロールを付与すると、エージェントプリンシパル ID がエージェントゲートウェイを介して登録済み宛先リソースにアクセスできるアクセスポリシーが有効になります。ポリシーはエージェントゲートウェイレベルで適用され、Identity-Aware Proxy（IAP）IAM ポリシーを使用して検証されます。

エージェントゲートウェイの下り（外向き）の IAM ロールを付与する

エージェントゲートウェイは、着信リクエストをチェックして、呼び出し元エージェントの ID がターゲットリソースに対する iap.webServiceVersions.egressViaIAP 権限（ロール roles/iap.egressor によって付与）を持っていることを検証します。

選択した宛先リソースでエージェント ID または Agent Runtime プリンシパルセットに roles/iap.egressor を付与すると、この下り（外向き）トラフィックが許可されます。この Codelab では、ロールはプリンシパル agent に適用され、特定の Agent Runtime エージェント ID に権限が付与されます。

IAM ポリシーは、エージェントレジストリのデータモデルで定義されている宛先リソースにバインドされます。iap_web/agentRegistry リソースは、IAM 階層の「レジストリ全体」レベルを表します。ここで、agentRegistry は agents、mcpServers、endpoints の個々の子リソースの親として機能します。この Codelab では、IAM ポリシーは mcpServer レベルと endpoint レベルにバインドされ、特定のサブリソースに権限が適用されます。

エージェントから MCP サーバーへのポリシーを構成する

エージェントから MCP サーバーへのポリシーを作成する

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

注: まだポリシーが定義されていないため、etag: はデフォルトの ACAB を返す必要があります。

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

エージェントのポリシーを MCP サーバーにバインドする

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

IAM 権限を確認する

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

ポリシーの説明は以上です。次は監査セクションに進みます。

12. 監査

Agent Gateway 認可拡張機能が DRY_RUN モードで動作しています。アウトバウンドリクエストは監視され、ログに記録されますが、ブロックされません。ENFORCED モードに切り替える前にログを分析すると、目的のトラフィックを許可するために構成する必要があるポリシーを確認できます。

エージェントのクエリをテストする

ブラウザウィンドウで Google Cloud コンソール UI を開き、次の場所に移動します。

Agent Platform → Agents → Deployments → agent-weather
[プレイグラウンド] タブを選択します。

または、このターミナルコマンドをエコーして、リンクをクリックしてエージェントのプレイグラウンドに移動します。

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

テストクエリを送信します。

What is the weather like in London?
How warm is it in New York?

クエリが有効なレスポンスを返すことを確認します。

監査ログを分析する

ログを表示し、ドライランポリシーの評価を検査します。

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

エージェントからエンドポイントへのポリシーを構成する

agent-weather のコア Google API はレジストリ（gapi.core.services）の共通エンドポイントサービスに登録されているため、エンドポイントアクセスにエージェントの下り（外向き）権限を付与するために必要なポリシーは 1 つだけです。

エージェントからエンドポイントへのポリシーを作成する

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

エージェントからエンドポイントへのポリシーをバインドする

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

IAM 権限を確認する

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

監査に関する説明は以上です。次は適用セクションに進みます。

13. 適用

エージェントは DRY_RUN モードでゲートウェイを介してリクエストを正常に実行できました。アクセスログとエンドポイントが分析され、エージェントからの必要な下り（外向き）トラフィックを許可する一連のガバナンスポリシーが作成されました。認可ポリシーを更新して、Agent Gateway IAP 認可拡張機能を ENFORCE モードに移行します。

認可拡張機能を更新する

認可拡張機能を作成する

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

認可拡張機能をインポートする

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

認可拡張機能を確認する

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

認可ポリシーを更新する

認可ポリシーを作成する

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

認可ポリシーをバインドする

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

認可ポリシーを検証する

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

適用を確認する

コンソール UI でエージェントのプレイグラウンドに戻ります。

[+ 新しいセッション] ボタンをクリックして、新しいチャットセッションを作成します。

追加のテストクエリを送信します。

What is the current temperature in Los Angeles?

Gemini 基盤モデル（${REGION}-aiplatform.googleapis.com/...）と MCP サーバーエンドポイント（mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp）へのエージェントリクエストが HTTP 200 OK ステータスコードで渡されることを確認します。

ゲートウェイログを分析する

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

ブロックされているリクエストがないことを確認します。ゲートウェイ監査ログで、HTTP 403 Forbidden ステータスコードで拒否された下り（外向き）試行を探します。

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Agent Gateway の MCP ログを表示し、MCP アプリケーションペイロード（JSON-RPC）が検査されて、実行されているツールなどのプロトコルメタデータが公開される方法を確認します。

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

ファイアウォールログを分析する

ネットワークファイアウォールポリシールールの優先度 1001 のログを表示します。

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

さまざまなトラフィックパスのネットワークレベルのビューを確認します。

subnet-${REGION}-agw を使用して内部 VPC ネットワークリソースと通信するエージェントゲートウェイ
subnet-${REGION}-crun を使用して外部の天気予報 API を呼び出す Cloud Run ホスト型 MCP サーバー

TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

DNS ログを分析する

限定公開 DNS ゾーン（priv-zone-run）によって解決されたリクエストの DNS クエリログを表示します。

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Cloud Run サービス（mcp-weather...run.app）の DNS ルックアップは、DNS ピアリングを使用して VPC ネットワークから発信され、Google API の内部 PSC エンドポイント（240.0.0.10）に正常に解決されます。

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

これで適用に関する説明は終わりです。次はクリーンアップ セクションに進みます。

14. クリーンアップ

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

これでクリーンアップは完了です。次はまとめに進みます。

15. まとめ

おめでとうございます！Agent Gateway が正常にデプロイされ、アウトバウンド AI エージェントトラフィックが制御されました。

cosmopup

Cosmopup は Codelab を最高だと思っています。

次のステップ

高度な機能とチュートリアルについては、Gemini Enterprise Agent Platform のドキュメントをご覧ください。
AI の安全性とセキュリティを強化するために、Agent Gateway で Model Armor ガードレールを構成する
セマンティックガバナンスポリシーを確認して、自然言語クエリのビジネスルールとコンプライアンスを適用する

ご意見、ご質問、修正点などがありましたら、こちらのフィードバックフォームからお気軽にお寄せください。

ありがとうございました

Agent Runtime から VPC ネットワークへの Agent Gateway 下り（外向き）

1. はじめに

構築内容

学習内容

必要なもの

2. コンセプト

デプロイ シーケンス

下り（外向き）ルーティング トポロジ

VPC 接続

3. セットアップ

必要な IAM のロール

プロジェクトにアクセスする

プロジェクト ID を設定する

セッションを認証する

シェル環境変数を設定する

gcloud cli を更新（推奨）

API サービスを有効にする

4. ネットワーク

ネットワークを作成する

ファイアウォール ルールの作成

PSC ネットワーク アタッチメントを作成する

PSC ネットワーク アタッチメントを確認する

PSC エンドポイントを作成する

PSC エンドポイントを確認する

DNS ゾーンとレコードを作成する

Cloud NAT を作成する

5. ゲートウェイ

ゲートウェイを作成

ゲートウェイを確認する

6. 承認

認可拡張機能

認可拡張機能を作成する

認可拡張機能をインポートする

認可拡張機能を確認する

認可ポリシー

認可ポリシーを作成する

認可ポリシーをバインドする

認可ポリシーを検証する

7. コードベース

リモート アーティファクトを取得する

ステージング バケットを作成する

8. レジストリ

エンドポイントの登録

エンドポイントの登録を確認する

9. MCP サーバー

デプロイの IAM 権限を付与する

IAM 権限を確認する

MCP サーバーをデプロイする

上り（内向き）の IAM 権限を付与する

ユーザー アクセスのポリシーをバインドする

IAM 権限を確認する

MCP 呼び出し用のカスタム SA を作成する

サービス アカウントのポリシーをバインドする

IAM 権限を確認する

認証用の IAM 権限を付与する

認証のバインド ポリシー

IAM 権限を確認する

MCP toolspec を作成する

MCP toolspec を検証する

Cloud Run 上り（内向き）を更新する

Cloud Run の上り（内向き）を確認する

MCP サーバーを登録する

MCP 登録を確認する

10. ADK エージェント

エージェントをデプロイする

デプロイメントを確認する

デプロイのバイタルを取得する

レジストリ エントリを確認する

ゲートウェイ構成を確認する

認証用の IAM 権限を付与する

認証（権限借用）のポリシーをバインドする

IAM 権限を確認する

ランタイムの IAM 権限を付与する

エージェント アクセスのバインド ポリシー

IAM 権限を確認する

11. ポリシー

エージェント ゲートウェイの下り（外向き）の IAM ロールを付与する

エージェントから MCP サーバーへのポリシーを構成する

エージェントから MCP サーバーへのポリシーを作成する

エージェントのポリシーを MCP サーバーにバインドする

デプロイシーケンス

下り（外向き）ルーティングトポロジ

`gcloud cli` を更新（推奨）

ファイアウォールルールの作成

PSC ネットワークアタッチメントを作成する

PSC ネットワークアタッチメントを確認する

リモートアーティファクトを取得する

ステージングバケットを作成する

ユーザーアクセスのポリシーをバインドする

サービスアカウントのポリシーをバインドする

認証のバインドポリシー

MCP `toolspec` を作成する

MCP `toolspec` を検証する

レジストリエントリを確認する

エージェントアクセスのバインドポリシー

エージェントゲートウェイの下り（外向き）の IAM ロールを付与する

ゲートウェイログを分析する

ファイアウォールログを分析する