Agent Runtime から Google MCP への Agent Gateway 下り

1. はじめに

この Codelab では、リモートの Google Cloud Model Context Protocol（MCP）サーバーにアクセスする AI エージェントの Agent Gateway 下り（外向き）ガバナンスについて説明します。

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

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

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

構築内容

• 下り（外向き）モード（エージェントから任意の宛先へ）の Agent Gateway
• Identity-Aware Proxy（IAP）認可拡張機能
• Agent Runtime ADK エージェント（エージェント ID 付き）
• Google API と MCP エンドポイントを含む Agent Registry
• IAM アクセス制御による認可ポリシー
• MCP を使用してクエリする BigQuery データセット

図 1. Codelab アーキテクチャ

学習内容

• 構造化された構成シーケンスで Agent Gateway をデプロイする方法
• 認可ポリシーをドライラン モードから適用モードに移行する方法
• Google API エンドポイントと MCP サーバーを Agent Registry に登録する方法
• Agent Gateway のログを監査して下り（外向き）ガバナンスを検証する方法

必要なもの

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

2. コンセプト

デプロイ シーケンス

ガバナンス制御を使用して Agent Gateway をデプロイする場合は、構造化された構成シーケンスに従って、エージェントが初期化時に必要なリソースにアクセスできるようにし、ネットワーク リクエストが成功するようにすることが重要です。

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

• ドライラン モードで開始する: ゲートウェイが完全にプロビジョニングされる前に、アウトバウンド通話をゲートウェイに転送するようにエージェント ランタイムが構成されている場合、ワークロードの初期化は失敗します。最初に DRY_RUN モードでゲートウェイ認証拡張機能を構成すると、エージェント トラフィックがゲートウェイに到達したときにリクエストがドロップされなくなります。
• すべてのサービスを登録する: Agent Gateway を使用するすべてのエージェント、MCP サーバー、エンドポイントは、Agent Registry に登録する必要があります。登録されていない送信元または宛先に対するリクエストは拒否されます。Agent Runtime と Google MCP サーバーにデプロイされたエージェントは自動的に登録されます。Google API エンドポイントまたはカスタム MCP サーバーは手動で登録する必要があります。
• 認可ポリシーを適用する: 認可ポリシーは、登録済みエージェントが エージェント コンポーネントにアクセスできるようにするために使用されます。これを行うには、エージェント ID プリンシパルにロール roles/iap.egressor を付与し、ターゲット レジストリ リソースにバインドします。ドライラン モードを使用してエージェントの動作を評価し、選択した上り（内向き）トラフィックがゲートウェイを通過できるようにポリシーを定義します。ポリシーが設定されたら、ENFORCED モードに切り替えて、ゲートウェイがガバナンス ポリシーを積極的に適用できるようにします。

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

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

ゲートウェイは通常、バックエンド サービスへのインバウンド トラフィック（上り）を管理します。下り（外向き）（エージェントから任意の場所）モードで動作する Agent Gateway は、エージェント ワークロード用の一元化されたゼロトラストのアウトバウンド プロキシとして機能します。

AI アプリまたはエージェント ワークロードが外部ツールまたは API を呼び出そうとすると、アウトバウンド リクエストは Agent Gateway によってインターセプトされ、宛先に転送される前にガバナンス ポリシーに対して評価されます。

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

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

この Codelab では、Agent Runtime のカスタム エージェントから BigQuery のリモート Google MCP サーバー エンドポイントをターゲットとするアウトバウンド トラフィックに焦点を当てます。

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 ポリシーを適用する
BigQuery	roles/bigquery.admin	スキーマとテスト用データセットを設定する
Cloud Storage	roles/storage.admin	デプロイ ステージング バケットを管理する
ログと監査	roles/logging.viewer	トレースと監査ログを検査する

または、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)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

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 \
  discoveryengine.googleapis.com

注: 一部の機能では gcloud beta コマンドを使用する場合があります。インストールされていない場合は、gcloud components install beta を実行して有効にします。

これでセットアップ部分は終了です。次は Gateway セクションに進みます。

4. ゲートウェイ

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

ここでは、Agent Gateway はリージョン レジストリを使用して、リージョン Agent Runtime リソースをサポートしています。

ゲートウェイを作成

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. 認可

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

1. Agent Gateway フロー: エージェントが外部エンドポイントまたは MCP サーバーを呼び出そうとすると、リクエストは Agent Gateway に転送されます。ゲートウェイは、アクセスをローカルで評価する代わりに、認可拡張機能を使用して IAP 評価サービスにコールアウトを送信します。IAP は、エージェント レジストリ内のターゲット リソースの IAM ポリシーに対して、エージェント（SPIFFE ベース）の ID を評価します。IAP は ALLOW または DENY の決定をゲートウェイに返します。ゲートウェイは、トラフィックを転送するか、HTTP 403 Forbidden ステータス コードでブロックします。
2. 適用モード: DRY_RUN モードでは、IAP はリクエストを評価し、トラフィックをブロックせずに Cloud Logging に決定を記録します。ENFORCE モードでは、未承認のエージェントからのリクエストや、登録されていないターゲットへのリクエストは直ちにブロックされます。
3. バインディング レイヤ: サービス拡張機能は、REQUEST_AUTHZ プロファイルで構成された認可ポリシーを使用して 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 (verify extension state)
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 (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

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

6. コードベース

この Codelab で使用するエージェント コード、BigQuery データセット、登録スクリプトは、リモートの 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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

BigQuery データセットを作成する

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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

# 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 セクションに進みます。

7. レジストリ

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

環境をブートストラップし、さまざまな Google API とサービスを使用してエージェントをサポートするために、スクリプトを使用して、endpoints/googleapis.txt のホスト名とロケーションを使用して共通の API エンドポイントのセットをすばやく登録します。

エンドポイントの登録

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

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

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

これでレジストリに関する説明は終わりです。次は Runtime セクションに進みます。

8. ランタイム

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

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

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

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

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

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

注: Agent Runtime にエージェントをデプロイすると、レジストリ リンク（RuntimeReference）が自動的に作成され、IAP 下り（外向き）ポリシー（RuntimeIdentity）に使用されるエージェント ID プリンシパルが公開され、動的エンドポイント検出（protocols.interfaces）が表示されます。

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

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

# verify agent gateway routing specification
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}'

確認: agentGateway に Gateway リソース URI が表示されていることを確認します。
"agentGateway": "projects/PROJ_ID/locations/REGION/agentGateways/agw-SLUG-REGION-ata"

リソースのエージェント IAM ロールを付与する

リソースに対する IAM ロールの付与により、エージェント プリンシパル ID は BigQuery、MCP ツール（Google API 用）、その他の必要な AI プラットフォーム サービスにアクセスできます。これらのポリシーは、リソース レベルで IAM を使用して適用されます。

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# 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 ロールを確認する

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

ランタイムに関する説明は以上です。次は ポリシーのセクションに進みます。

9. ポリシー

エージェント ガバナンス認可ポリシーにより、AI エージェントからのトラフィックが Agent Gateway を通過して宛先（BigQuery の Google Cloud MCP サーバー エンドポイントなど）に到達することが許可されます。トラフィックが宛先に到達すると、通常の IAM 権限によってデータアクセスが承認されます（前のセクションで有効にしました）。

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

Agent Gateway の下り（外向き）用にエージェントの IAM ロールを付与する

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

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

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

NOTE: 本番環境のデプロイでは、よりきめ細かいポリシーを実装して、特定のエージェントから特定のエンドポイントへの下り（外向き）を制限できます。きめ細かい制御と条件付き許可ポリシーについては、今後の Codelab で説明します。

IAP リージョン レジストリの IAM ポリシーを構成する

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

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

10. 監査

Agent Gateway 認可拡張機能が DRY_RUN モードで動作しています。アウトバウンド リクエストは監視され、ログに記録されますが、ブロックされません。

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

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

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

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

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

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

• How many DJs do we have on file?
• What is the phone number of DJ Cosmopup?

クエリが有効なレスポンス（「12 人の DJ が登録されています」など）を返すことを確認します。

監査ログを分析する

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

# query gateway logs for dry run
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
  )"

確認: IAP_AUTHZ の結果に ALLOWED が表示されていることを確認します。

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. 適用

エージェントは 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 でエージェントの [Playground] に戻ります。

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

• What DJ Fishfry's credit card number?

Gemini 基盤モデル（${REGION}-aiplatform.googleapis.com/...）と MCP サーバー エンドポイント（bigquery.googleapis.com/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
  )"

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

12. クリーンアップ

# delete agent
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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "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 storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
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}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. まとめ

おめでとうございます！Agent Gateway を使用してツールにアクセスするエージェントのアウトバウンド通信が正常にデプロイされ、管理されました。

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

次のステップ

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

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

ありがとうございました