このページでは、Agent Runtime トラフィックを Agent Gateway 経由でルーティングする方法について説明します。Agent Gateway は、Gemini Enterprise Agent Platform エコシステムの中心的なネットワーキング コンポーネントとセキュリティ コンポーネントです。 ユーザーとエージェント間、エージェントとツール間、エージェント同士のやり取りなど、すべてのエージェントのやり取りに対して安全で管理された接続を提供します。
始める前に
Agent Runtime にエージェントをデプロイする方法を 理解しておいてください。
Agent Gateway について学習します。 . Agent Gateway を Agent-to-Anywhere(下り)モードで使用すると、ツール、モデル、API、他のエージェントへの下りトラフィックを含む、すべてのアウトバウンド通信を保護し、管理できます。Client-to-Agent(上り)モードでゲートウェイを使用すると、エージェントにアクセスできるクライアントを制御できます。ゲートウェイを使用すると、これらのやり取りに適用する必要がある IAP ポリシーと Model Armor テンプレートを選択できます。
1 つの Runtime インスタンスは、Agent-to-Anywhere(下り)ゲートウェイと Client-to-Agent(上り)ゲートウェイの両方に同時にバインドできます。
制限事項
- Agent Gateway は、2026 年 4 月 29 日より前に作成された Runtime 推論エンジンにバインドできません。
1 つのプロジェクトとリージョンで複数の Agent-to-Anywhere(下り)と Client-to-Agent(上り)の Agent Gateway インスタンスをホストできますが、同じプロジェクトとリージョン内にデプロイされたすべての Agent Runtime エージェントは、同じ特定の下りおよび上りの Agent Gateway インスタンスにバインドする必要があります。
たとえば、プロジェクトとリージョンに
egress-gateway-Xとegress-gateway-Yが含まれている場合、そのプロジェクトとリージョン内のすべてのエージェントは、下り用に同じゲートウェイを使用するように構成する必要があります。つまり、すべてのエージェントがegress-gateway-Xを使用するか、すべてのエージェントがegress-gateway-Yを使用します。agent-Aがegress-gateway-Xを使用し、agent-Bがegress-gateway-Yを使用するように構成することはできません。この同じバインディング ルールは、プロジェクトとリージョン内の上りゲートウェイにも適用されます。
エージェントで Agent Gateway が有効になっている場合、Security Command Center Agent Engine Threat Detection サービス は使用できません。
Client-to-Agent(上り)モードでは、Agent Gateway は Agent Runtime の
queryメソッドとstreamQueryメソッドのみを管理できます。サポートされていない他のメソッド(asyncQueryなど)を保護するには、アプリケーションまたはエージェントから Model Armor テンプレートを直接適用します。プロンプトと レスポンスのサニタイズまたは Model Armor を使用して安全なエージェント システムを構築する の Codelab をご覧ください。VPC Service Controls は Agent Gateway ではサポートされていません。
Agent Runtime トラフィックを Agent Gateway 経由でルーティングする
Agent Runtime トラフィックを Agent Gateway 経由でルーティングする手順は次のとおりです。
Agent Gateway リソースを作成し、必要に応じて承認ポリシーをアタッチします。ゲートウェイは、Agent-to-Anywhere(下り)モードまたは Client-to-Agent(上り)モードで作成できます。エージェントとゲートウェイは、同じプロジェクトとリージョンに作成する必要があります。手順については、Agent Gateway を設定するをご覧ください。
ゲートウェイがデプロイのニーズを満たすように構成されていることを確認します。たとえば、エージェントに LLM アクセスが必要な場合は、このアクセスを許可するようにゲートウェイを構成して、Agent Runtime のデプロイが失敗する可能性を防ぎます。
Agent Gateway 経由でトラフィックをルーティングするようにエージェントを構成します。
新しいエージェントの場合
エージェントのデプロイ時にゲートウェイ リソースを指定します。たとえば、エージェントを Agent Runtime にデプロイするには、
client.agent_engines.createを使用して、local_agentオブジェクトと任意の 構成を渡します。このエージェントで Model Armor や Semantic Governance Policies などのゲートウェイを介したプラットフォーム機能を使用する場合は、この例に示すように、作成呼び出しで
agent_gateway_configとidentity_type=AGENT_IDENTITYの両方を設定します。identity_type=AGENT_IDENTITYがないと、Runtime インスタンスのeffectiveIdentityはデフォルトの Vertex AI サービス アカウントにフォールバックし、Semantic Governance Policies はポリシー作成セレクタからエージェントをサイレントにフィルタします。remote_agent = client.agent_engines.create( agent=local_agent, config={ "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}, # "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME} }, "identity_type": types.IdentityType.AGENT_IDENTITY, # Other optional configuration ... # "requirements": requirements, # "gcs_dir_name": gcs_dir_name, # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa "env_vars": { "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False, } }, )
AGENT_GATEWAY_TO_ANYWHERE_NAMEは、Agent-to-Anywhere(下り)モードで作成した Agent Gateway の名前に置き換えます。Client-to-Agent(上り)モードでゲートウェイを作成した場合は、代わりに
client_to_agent_configフィールドを使用し、AGENT_GATEWAY_CLIENT_TO_AGENT_NAMEを上り用に作成した Agent Gateway の名前に置き換えます。既存のエージェントの場合
Agent-to-Anywhere
次の REST API リクエストを使用して、既存のエージェントを下りのAgent-to-Anywhere ゲートウェイ に関連付けます。
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "spec": { "deploymentSpec": { "agentGatewayConfig": { "agentToAnywhereConfig": { "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME" } } } } }' \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"
次のように置き換えます。
PROJECT_ID: プロジェクト IDREGION: エージェントがデプロイされているリージョンAGENT_GATEWAY_TO_ANYWHERE_NAME: Agent-to-Anywhere(下り)モードで作成した Agent Gateway の名前RESOURCE_ID: エージェントのリソース ID
Client-to-Agent
次の REST API リクエストを使用して、既存のエージェントを上りのClient-to-Agent ゲートウェイ に関連付けます。
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "spec": { "deploymentSpec": { "agentGatewayConfig": { "clientToAgentConfig": { "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME" } } } } }' \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"
次のように置き換えます。
PROJECT_ID: プロジェクト IDREGION: エージェントがデプロイされているリージョンAGENT_GATEWAY_CLIENT_TO_AGENT_NAME: Client-to-Agent(上り)で作成した Agent Gateway の名前RESOURCE_ID: エージェントのリソース ID
エージェントとゲートウェイと同じプロジェクトとリージョンにある Agent Registry インスタンスに登録します。
gcloud agent-registry services create SERVICE_NAME \ --project=PROJECT_ID \ --location=REGION \ --display-name="DISPLAY_NAME" \ --endpoint-spec-type=no-spec \ --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \ --format="value(registryResource)"次のように置き換えます。
SERVICE_NAME: リソースに付ける名前(allow-aiplatform-region-eu3など)。PROJECT_ID: プロジェクト ID。REGION: レジストリ リージョン。DISPLAY_NAME: エンドポイントの人間が読める名前。
詳細については、 エージェントを登録するをご覧ください。
エージェントの Agent-to-Registry IAM ポリシー バインディングを作成します。
gcloud iap web add-iam-policy-binding \ --resource-type=agent-registry \ --endpoint=ENDPOINT_ID \ --region=REGION \ --project=PROJECT_ID \ --member=MEMBER \ --role=roles/iap.egressor
次のように置き換えます。
ENDPOINT_ID: 登録済みエージェントのサービス エンドポイント ID。これは、前の手順の出力から取得します。MEMBER: ロールを付与するエージェント ID プリンシパル。通常、形式は:principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_IDです。
この時点で、エージェント トラフィックは Agent Gateway 経由で転送されます。ただし、Agent Gateway はデフォルトで拒否ポリシーを採用しています。 特定の Agent Platform 機能を有効にするには、エージェントが次のエンドポイントと通信できることを確認する必要があります。
Cloud Trace が有効になっている場合、Agent Gateway はエンドポイント
https://telemetry.googleapis.com/へのトラフィックを許可する必要があります。GOOGLE_API_USE_CLIENT_CERTIFICATE環境変数とGOOGLE_API_USE_MTLS_ENDPOINT環境変数が設定されている場合は、https://telemetry.mtls.googleapis.com/へのトラフィックも許可されていることを確認してください。Cloud Logging が有効になっている場合、Agent Gateway はエンドポイント
https://logging.googleapis.com/へのトラフィックを許可する必要があります。GOOGLE_API_USE_CLIENT_CERTIFICATE環境変数とGOOGLE_API_USE_MTLS_ENDPOINT環境変数が設定されている場合は、https://logging.mtls.googleapis.com/へのトラフィックも許可されていることを確認してください。
また、エージェントが LLM を呼び出す場合や、 セッションや メモリ バンクなどの機能を使用する場合は、エージェントがこれらのサービスで使用されるエンドポイントと通信できることを確認する必要があります。 次に例を示します。
- セッションの場合:
https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions - メモリバンクの場合:
https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories
セキュリティ上の理由から、エージェントがアクセスする特定の URI のみを登録して許可リストに登録することをおすすめします。ゲートウェイはホスト名を直接照合するため、エージェント SDK が使用するすべてのバリアントを登録する必要があります。たとえば、SDK のバージョン、リージョン クライアント構成、mTLS の使用状況に応じて、Google API は次のエンドポイント ホスト名を介して解決できます。
https://REGION-aiplatform.googleapis.comhttps://REGION-aiplatform.mtls.googleapis.comhttps://aiplatform.REGION.rep.googleapis.com
エンドポイントを登録する方法については、エンドポイントを登録するをご覧ください。また、エージェントにこれらのエンドポイントの IAP Egressor ロールがあることを確認する必要があります。手順については、エージェントからエンドポイントへの下りポリシー を作成するをご覧ください。
エージェントの構成を確認します。
コンソール
- コンソールで、Agent Platform の [デプロイ] ページに移動します。 Google Cloud
デプロイしたエージェントの名前をクリックします。
[サービス構成] をクリックします。エージェントの [オブザーバビリティ] ペインが開きます。
[デプロイの詳細] をクリックします。Agent Gateway の上り構成と下り構成は、[デプロイ仕様] フィールドにあります。
gcloud
次の REST API リクエストを使用して、エージェントがゲートウェイに関連付けられていることを確認します。返された出力が
nullの場合、Runtime はゲートウェイにバインドできませんでした。curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \ | jq '.spec.deploymentSpec.agentGatewayConfig'
次のように置き換えます。
PROJECT_ID: プロジェクト IDREGION: エージェントがデプロイされているリージョンRESOURCE_ID: エージェントのリソース ID
- コンソールで、Agent Platform の [デプロイ] ページに移動します。 Google Cloud
Agent Gateway 用にカスタム コンテナ(BYOC)エージェントを構成する
カスタム コンテナ イメージ(Bring Your Own Container / BYOC)でデプロイされたエージェントのアウトバウンド トラフィックを Agent-to-Anywhere(下り) Agent Gateway 経由でルーティングする場合は、 ゲートウェイのルート認証局(CA)証明書を カスタム コンテナ イメージのトラストストアにベイクする必要があります。
Agent Gateway は、エージェントのアウトバウンド通信に対して TLS 復号と検査を行うため、BYOC 以外の(ソースベースの)エージェント デプロイでは、イメージの作成時に CA 証明書が自動的に挿入されます。カスタム コンテナ イメージの場合は、ゲートウェイの CA 証明書を明示的に取得し、Dockerfile 内のシステム CA トラストストアにインストールして、Python SDK、HTTP クライアント ライブラリ、gRPC で必要な証明書バンドル環境変数を設定する必要があります。
Agent Gateway の下り用に BYOC コンテナ イメージを構成する手順は次のとおりです。
Agent Gateway リソースからルート証明書を取得します。
CA ルート証明書の PEM 文字列を Agent Gateway リソースの
agentGatewayCard.rootCertificatesフィールドから直接エクスポートします。export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \ --location=REGION \ --project=PROJECT_ID \ --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")
または、REST API を使用してゲートウェイ リソースを取得することもできます。
curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://networkservices.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \ | jq -r '.agentGatewayCard.rootCertificates[]'
次のように置き換えます。
AGENT_GATEWAY_NAME: 下り Agent Gateway の名前REGION: ゲートウェイがデプロイされているリージョンPROJECT_ID: プロジェクト ID
CA 証明書を信頼するように
Dockerfileを更新します。AGENT_GATEWAY_ROOT_CERTIFICATESビルド引数をDockerfileに追加します。ビルドコマンドは、証明書を個別のファイルに分割し、update-ca-certificatesを使用してインストールし、OpenSSL、Python HTTP クライアント ライブラリ(requests、httpx)、gRPC がカスタム CA を認識するように環境変数を設定します。# Install root certificates under root user USER root ARG AGENT_GATEWAY_ROOT_CERTIFICATES RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \ echo "Installing Agent Gateway root certificates..."; \ printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \ update-ca-certificates; \ fi # Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt} # Switch back to application execution user USER 1000
Cloud Build を使用してコンテナ イメージをビルドします。
cloudbuild.yamlファイルを作成して、置換を使用してルート証明書文字列を Cloud Build に渡します。steps: - name: 'gcr.io/cloud-builders/docker' args: - 'build' - '--build-arg' - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}' - '-t' - '$_IMAGE_URI' - '.' images: - '$_IMAGE_URI'コンテナ イメージのビルドを Cloud Build に送信します。
export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest" gcloud builds submit \ --project=PROJECT_ID \ --region=REGION \ --config=cloudbuild.yaml \ --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \ .
REPOSITORY_NAMEとIMAGE_NAMEは、Artifact Registry のリポジトリ名とイメージ名に置き換えます。コンテナ化されたエージェントをデプロイします。
デプロイ リクエストで、ビルドされたコンテナ イメージの URI と Agent Gateway の構成を指定します(
spec.deploymentSpecのagent_gateway_configを使用するか、SDK デプロイ呼び出しを使用します)。
Agent Runtime を承認済みの Agent Gateway に制限する
カスタムの組織のポリシー制約を作成して、エージェントのデプロイ時に使用できる対象となる Agent Gateway リソースのセットを定義できます。
カスタムの組織のポリシー制約を作成する
この例では、事前承認されたゲートウェイのリストとの間のトラフィックのみを許可するカスタム制約を作成します。
Agent-to-Anywhere
Agent-to-Anywhere モード(下り)のカスタム制約を定義するには、
constraint-agent-gateway-egress.yamlという名前のファイルを作成します。次の例では、
conditionフィールドは、Agent Gateway リソースが指定されている場合(フィールドが存在し、空でない場合)にのみオペレーションが許可され、指定されたゲートウェイが事前承認リストに含まれている場合にのみオペレーションが許可されることを指定します。name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine resource_types: - aiplatform.googleapis.com/ReasoningEngine condition: >- has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) && resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' && (resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [ 'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1', 'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2', ]) method_types: - CREATE - UPDATE action_type: ALLOW display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways description: Reasoning Engines can only be bound to a pre-approved list of Agent Gateway instances. Binding to any other gateway is denied.次のように置き換えます。
- ORGANIZATION_ID: 組織 ID。
- AGENT_PROJECT_ID: プロジェクト ID。
- REGION: ゲートウェイが作成されたリージョン。
- AGENT_GATEWAY_ID: ゲートウェイ ID。
カスタム制約を適用します。
gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
EGRESS_CONSTRAINT_PATH は、前の手順で作成したカスタム 制約ファイルのフルパスに置き換えます。
制約を適用する組織のポリシーを作成します。組織のポリシーを定義するには、
policy-agent-gateway-egress.yamlという名前のポリシー YAML ファイルを作成します。この例では、この制約をプロジェクト レベルで適用しますが、組織レベルまたはフォルダレベルで設定することもできます。name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine spec: rules: - enforce: trueAGENT_PROJECT_IDは、実際のプロジェクト ID に置き換えます。組織のポリシーを適用します。
gcloud org-policies set-policy EGRESS_POLICY_PATH
EGRESS_POLICY_PATH は、前の手順で作成した組織のポリシー YAML ファイルのフルパスに置き換えます。ポリシーが有効になるまでに最大 15 分かかります。
Client-to-Agent
Client-to-Agent モード(上り)のカスタム制約を定義するには、
constraint-agent-gateway-ingress.yamlという名前のファイルを作成します。次の例では、
conditionフィールドは、Agent Gateway リソースが指定されている場合(フィールドが存在し、空でない場合)にのみオペレーションが許可され、指定されたゲートウェイが事前承認リストに含まれている場合にのみオペレーションが許可されることを指定します。name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine resource_types: - aiplatform.googleapis.com/ReasoningEngine condition: >- has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) && resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' && (resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [ 'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1', 'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2', ]) method_types: - CREATE - UPDATE action_type: ALLOW display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways description: Reasoning Engines can only be bound to a pre-approved list of Agent Gateway instances. Binding to any other gateway is denied.次のように置き換えます。
- ORGANIZATION_ID: 組織 ID。
- AGENT_PROJECT_ID: プロジェクト ID。
- REGION: ゲートウェイが作成されたリージョン。
- AGENT_GATEWAY_ID: ゲートウェイ ID。
カスタム制約を適用します。
gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
INGRESS_CONSTRAINT_PATH は、前の手順で作成したカスタム 制約ファイルのフルパスに置き換えます。
制約を適用する組織のポリシーを作成します。組織のポリシーを定義するには、
policy-agent-gateway-ingress.yamlという名前のポリシー YAML ファイルを作成します。この例では、この制約をプロジェクト レベルで適用しますが、組織レベルまたはフォルダレベルで設定することもできます。name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine spec: rules: - enforce: trueAGENT_PROJECT_IDは、実際のプロジェクト ID に置き換えます。組織のポリシーを適用します。
gcloud org-policies set-policy INGRESS_POLICY_PATH
INGRESS_POLICY_PATH は、前の手順で作成した組織のポリシー YAML ファイルのフルパスに置き換えます。ポリシーが有効になるまでに最大 15 分かかります。
カスタムの組織のポリシー制約の使用方法の詳細については、 カスタム制約を作成するをご覧ください。
次のステップ
Codelab: Agent Platform でエージェント ワークロードを管理する
Gemini Enterprise Agent Platform で Agent Gateway を使用してエージェント ワークロードを管理する方法を学習します。