Agent Gateway を管理する

このドキュメントでは、Agent Gateway リソースのデプロイ後のメンテナンス タスクについて説明します。ゲートウェイをまだ作成していない場合は、Agent Gateway を設定するをご覧ください。

始める前に

Agent Gateway リソースを管理する前に、次の前提条件を確認してください。

  • ゲートウェイ、接続テンプレート、認可ポリシー、認可拡張機能を表示、更新、削除するために必要な権限があることを確認します。権限の完全なリストについては、必要な権限をご覧ください。
  • プロジェクトで必要なサービスを有効にします。詳細については、必要な API をご覧ください。
  • ワークロードをゲートウェイから関連付け解除する予定がある場合は、Gemini Enterprise Agent Platform の Agent Runtime デプロイまたは Gemini Enterprise アプリを管理する権限も必要です。

ゲートウェイを表示して検査する

Google Cloudプロジェクトの Agent Gateway リソースを一覧表示し、ゲートウェイの構成、アタッチされた拡張機能、出力専用メタデータを検査できます。

コンソール

  1. Google Cloud コンソールで、[ゲートウェイ] ページに移動します。

    [ゲートウェイ] に移動

  2. 選択したプロジェクトのゲートウェイのリストを表示します。

  3. ゲートウェイの名前をクリックして、詳細ページを開きます。

    • [詳細] タブで、[概要]、[アクセス認可]、[AI セキュリティ]、[サービス拡張機能]、[VPC 構成] の各セクションを確認します。
    • [オブザーバビリティ] タブで、ゲートウェイ トラフィックとポリシーの指標を確認します。詳細については、Agent Gateway のトラフィックをモニタリングするをご覧ください。

gcloud

  • 特定のリージョン内のすべてのゲートウェイを一覧表示します。

    gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID

    次のように置き換えます。

    • LOCATION: ゲートウェイがデプロイされているリージョン（us-central1 など）。
    • PROJECT_ID: ゲートウェイをホストする Google Cloudプロジェクトの ID。

  • 特定のゲートウェイの構成を検査します。

    gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    AGENT_GATEWAY_NAME は、Agent Gateway リソースの名前に置き換えます。

変更不可の設定

関連付けられた Agent Registry インスタンスやセキュリティ ポリシー、ガバナンス ポリシーなど、ほとんどの Agent Gateway 構成は、Agent Gateway を更新するの説明に沿って、その場で変更できます。ただし、特定のコア構成は不変であり、代替ゲートウェイをデプロイする必要があります。ゲートウェイを変更する前に、次の表を確認してください。

設定 可変性 要件または制限
ゲートウェイの名前とリージョン 変更不可 名前またはリージョンを変更するには、代替ゲートウェイをデプロイします。

管理対象アクセスパス

（AGENT_TO_ANYWHERE または CLIENT_TO_AGENT）

 変更不可 googleManaged.governedAccessPath での作成時に構成されます。インプレースで変更することはできません。

Private Service Connect ネットワーク アタッチメント

（networkAttachment）

 設定後は変更不可 ネットワーク アタッチメントをゲートウェイに関連付けると、変更や削除はできません。

エージェント接続テンプレートと、関連する Cloud DNS ピアリング、TLS 信頼構成、VPC 下り（外向き）設定

 条件付きで変更可能 新しいテンプレートが同じ networkAttachment を参照している限り、ゲートウェイの構成を更新して、新しい設定で別の接続テンプレートを参照できます。

ゲートウェイを交換して不変の設定を変更する

ゲートウェイに関連付けられた PSC ネットワーク アタッチメントなど、不変の設定を変更する必要がある場合は、代替ゲートウェイをデプロイして、ワークロードを新しいゲートウェイに移行する必要があります。

  1. 代替の Agent Gateway を作成し、Identity and Access Management（IAM）ポリシーと認可ポリシーを構成します。手順については、Agent Gateway を設定するをご覧ください。

  2. 代替ゲートウェイを使用するようにワークロードを更新します。

    • Gemini Enterprise アプリ: アプリの [セキュリティ] > [構成] 設定で、ゲートウェイ リソース名を更新します。Agent Gateway 経由で Gemini Enterprise トラフィックをルーティングするをご覧ください。
    • Agent Runtime エージェント: 単一のプロジェクトとリージョン内で、すべての Agent Runtime エージェントを同じゲートウェイにバインドする必要があります。あるゲートウェイから別のゲートウェイへの直接のインプレース アップデートはサポートされていません。エージェントを移行するには:
      1. バインドされたすべてのエージェントがトラフィックの 100% を最新のリビジョン（trafficConfig.trafficSplitAlwaysLatest）にルーティングするようにします。
      2. reasoningEngines.patch を使用して spec.deploymentSpec.agentGatewayConfig を {} に設定し、プロジェクトとリージョン内のすべてのエージェントと以前のゲートウェイの関連付けを解除し、各更新オペレーションが完了するまで待ちます。
      3. 各エージェントで reasoningEngines.patch を呼び出して、spec.deploymentSpec.agentGatewayConfig を置換ゲートウェイ リソース名に設定します。リクエストの例については、Agent Gateway を介して Agent Runtime トラフィックをルーティングするをご覧ください。

  3. すべてのワークロードが以前のゲートウェイを参照しなくなったら、Agent Gateway を削除するの手順に沿って、以前のゲートウェイを削除します。

Agent Gateway を更新する

特定の Agent Gateway 構成を Google Cloud コンソールで直接更新するか、gcloud CLI を使用してゲートウェイ構成を YAML ファイルにエクスポートし、変更を加えてファイルを再インポートできます。

Agent Registry を更新する

関連付けられた Agent Registry は、Google Cloud コンソールまたは gcloud CLI で更新できます。ゲートウェイは、ゲートウェイのリージョンに対応する単一のリージョン レジストリを参照する必要があります。ゲートウェイが Gemini Enterprise アプリにリンクされている場合、ゲートウェイはそのアプリのロケーションに一致する単一のレジストリを保持する必要があります。

コンソール

  1. Google Cloud コンソールで、[ゲートウェイ] ページに移動します。

    [ゲートウェイ] に移動

  2. 更新するゲートウェイの名前をクリックします。

  3. [詳細] タブの [概要] セクションで、[レジストリを編集] をクリックします。

  4. ゲートウェイがデプロイされているリージョンと一致するリージョン Agent Registry を選択し、[保存] をクリックします。

gcloud

gcloud network-services agent-gateways export を使用してゲートウェイ構成を agent-gateway.yaml にエクスポートし、registries、description、または labels を編集して（createTime、updateTime、agentGatewayCard、selfLink などの出力専用フィールドを削除）、ゲートウェイの接続テンプレートを更新するに示されているように、gcloud network-services agent-gateways import を使用してファイルを再インポートします。

接続テンプレートを更新する

Agent Gateway リソースの接続テンプレートを更新するには、gcloud CLI を使用します。

gcloud

  1. 更新された接続設定を使用して新しい AgentConnectivityTemplate を作成し、既存のゲートウェイと同じ networkAttachment を使用するようにします。テンプレートの構文と構成手順の詳細については、VPC 接続を使用して Agent Gateway を設定するをご覧ください。

  2. 既存のゲートウェイ構成を YAML ファイルにエクスポートします。

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

    次のように置き換えます。

    • AGENT_GATEWAY_NAME: 更新するゲートウェイの名前。
    • LOCATION: ゲートウェイがデプロイされているリージョン。
    • PROJECT_ID: ゲートウェイがデプロイされているプロジェクト ID。

  3. エクスポートされた agent-gateway.yaml ファイルで、既存の protocols、registries、description、labels フィールドをそのまま保持し、出力専用フィールド（createTime、updateTime、agentGatewayCard、selfLink）を削除して、新しいテンプレートを参照するように agentConnectivityTemplate を更新します。

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME

    次のように置き換えます。

    • PROJECT_NUMBER: ゲートウェイがデプロイされている数値のプロジェクト番号（agentConnectivityTemplate には、プロジェクト ID ではなくプロジェクト番号が必要です）。
    • LOCATION: ゲートウェイのリージョン。
    • AGENT_GATEWAY_NAME: ゲートウェイの名前。
    • NEW_TEMPLATE_NAME: 置換接続テンプレートの名前。

  4. 更新した YAML ファイルを再度インポートして、変更を適用します。

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

  5. オプション：ゲートウェイの更新が完了したら、以前の接続テンプレートを削除してください。

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

IAP 設定または Model Armor テンプレートを変更する

IAP の適用設定と Model Armor テンプレートを変更するには、ゲートウェイに接続されている認可拡張機能を更新します。

コンソール

  1. Google Cloud コンソールで、[ゲートウェイ] ページに移動します。

    [ゲートウェイ] に移動

  2. 更新するゲートウェイの名前をクリックします。

  3. [詳細] タブで、接続されているセキュリティ拡張機能を更新します。

    • IAP 自動適用モードを変更する: [アクセス認可] セクションで、[アクセス認可] の横にある [アクセス認可を編集] をクリックします。[監査のみ]（ドライラン モード）または [ポリシーを適用する] を選択し、[保存] をクリックします。

    • Model Armor テンプレートを変更する: [AI セキュリティ] セクションで、[リクエストのテンプレート] の横にある [リクエスト テンプレートを編集] または [レスポンスのテンプレート] の横にある [レスポンス テンプレートを編集] をクリックします。置換テンプレートを選択し、[保存] をクリックします。

gcloud

  1. ゲートウェイのリージョン内の認可拡張機能を一覧表示して、拡張機能の名前を特定します。

    gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID

    LOCATION はゲートウェイのリージョンに、PROJECT_ID はプロジェクト ID に置き換えます。

  2. 拡張機能の現在の構成を確認します。

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

    AUTHZ_EXTENSION_NAME は、IAP または Model Armor の AuthzExtension リソースの名前に置き換えます。

  3. 更新した拡張機能の仕様を authz-extension.yaml に保存します。createTime や updateTime などの出力専用フィールドは省略します。

    • IAP 拡張機能の場合: 監査専用モードの場合は iamEnforcementMode: "DRY_RUN" を含めます。ポリシーを適用する場合は iamEnforcementMode を削除します。

      name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies

    • Model Armor 拡張機能の場合: metadata.model_armor_settings の request_template_id と response_template_id を更新します。

      name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'

      次のように置き換えます。

      • AUTHZ_EXTENSION_NAME: Model Armor AuthzExtension リソースの名前。
      • LOCATION: ゲートウェイのリージョン。
      • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートをホストするプロジェクト ID。
      • REQUEST_TEMPLATE_ID、RESPONSE_TEMPLATE_ID: リクエスト テンプレートとレスポンス テンプレートの ID。

      ゲートウェイ サービス アカウント（agentGatewayCard.serviceExtensionsServiceAccount）に、新しく参照されたテンプレート プロジェクトに対する roles/modelarmor.user と、ゲートウェイ プロジェクトに対する roles/modelarmor.calloutUser と roles/serviceusage.serviceUsageConsumer が付与されていることを確認します（認可を委任するをご覧ください）。

  4. 更新された拡張機能の YAML ファイルをインポートします。

    gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
 --source="authz-extension.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

新しい認可ポリシーを接続するか、既存の AuthzPolicy でトラフィック マッチング ルールを変更するには、認可を委任するをご覧ください。

Agent Gateway からワークロードの関連付けを解除する

Agent Gateway を削除する前に、その Agent Gateway を参照するすべての Gemini Enterprise app と Agent Runtime エージェントの関連付けを解除する必要があります。

Gemini Enterprise app の関連付けを解除する

Google Cloud コンソールで、Gemini Enterprise app から Agent Gateway のリンクを解除できます。

  1. Google Cloud コンソールで、[Gemini Enterprise] ページに移動します。

    Gemini Enterprise に移動

  2. ゲートウェイに関連付けられているアプリの名前をクリックします。

  3. [セキュリティ] をクリックします。

  4. [構成] タブの [Agent Gateway の構成] で、[Agent Gateway のリソース名] フィールドをクリアします。

  5. [保存] をクリックします。

Agent Gateway の関連付けを解除すると、アプリのアウトバウンド トラフィックがゲートウェイ経由でルーティングされなくなります。インポートされたエージェントと Model Context Protocol（MCP）サーバーは Agent Registry に登録されたままになりますが、ゲートウェイを再度リンクするまで、アプリはそれらにアクセスできません。新しいゲートウェイは、同じ Agent Registry を参照する必要があります。

Agent Runtime エージェントの関連付けを解除する

Google Cloud コンソールと gcloud CLI では、Agent Runtime ゲートウェイ バインディングの変更はサポートされていません。エージェントを実行したまま、デプロイされた Agent Runtime エージェントから Agent Gateway の関連付けを解除するには、reasoningEngines.patch REST API メソッドを呼び出して spec.deploymentSpec.agentGatewayConfig をクリアします。

  1. エージェントがすべてのトラフィックを最新リビジョンにルーティングするようにします（trafficConfig.trafficSplitAlwaysLatest が true に設定されているか、手動の trafficConfig 分割が構成されていない）。手動リビジョン トラフィック分割が有効で、以前のすべてのリビジョンが不可逆的にアーカイブされている場合、ゲートウェイ バインディングのクリアまたは変更は失敗します。詳細については、Agent Gateway とリビジョンをご覧ください。

  2. updateMask=spec.deploymentSpec.agentGatewayConfig と空の agentGatewayConfig オブジェクト（{}）を含む PATCH リクエストを推論エンジンに送信します。

    curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
   "spec": {
     "deploymentSpec": {
       "agentGatewayConfig": {}
     }
   }
 }' \
 "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

    次のように置き換えます。

    • REGION: エージェントがデプロイされているリージョン。
    • PROJECT_ID: エージェントがデプロイされているプロジェクト ID。
    • RESOURCE_ID: エージェントのリソース ID。

Agent Gateway を削除する

Agent Gateway は、孤立したセキュリティ ポリシーやエージェント トラフィック パスの破損を防ぐために、厳格な参照トラッキングを適用します。次のいずれかの条件に該当する場合、ゲートウェイの削除は失敗し、 Google Cloud コンソールの [削除] ボタンは使用できないままになります。

  • 1 つ以上の Agent Runtime エージェントまたは Gemini Enterprise app が、引き続きゲートウェイを参照しています。
  • AuthzPolicy（IAP、Model Armor、カスタム プロバイダの場合）または TelemetryPolicy は、引き続きゲートウェイをターゲットにします。
  • VPC 構成の更新オペレーションがゲートウェイでまだ実行されています。

Agent Gateway を削除して、関連するリソースをクリーンアップするには、次の手順を順番に実施します。

コンソール

  1. Gemini Enterprise app または Agent Runtime エージェントがゲートウェイを参照していないことを確認します。Agent Gateway からワークロードの関連付けを解除するの手順に沿って操作します。

  2. Google Cloud コンソールで、[ゲートウェイ] ページに移動します。

    [ゲートウェイ] に移動

  3. 削除するゲートウェイの名前をクリックします。

  4. [詳細] タブで、ゲートウェイをターゲットとするすべてのポリシーの関連付けを削除します。

    • [アクセス承認] セクションが表示されたら、[削除] をクリックして、削除を確定します。この操作を行うと、IAP AuthzPolicy とその AuthzExtension の両方が削除されます。
    • [AI Security] セクションが表示されたら、[削除] をクリックして、削除を確定します。この操作を行うと、Model Armor の AuthzPolicy とその AuthzExtension の両方が削除されます。
    • [サービス拡張機能] テーブルを確認します。カスタム AuthzPolicy リソースが接続されたままになっている場合は、この手順の gcloud タブを使用して削除してから続行します。

  5. すべてのポリシーの関連付けが削除され、VPC の更新が進行中でない場合は、[削除] をクリックして、削除を確定します。

  6. プロジェクトの [ゲートウェイ] リストにゲートウェイが表示されなくなったことを確認します。

  7. 省略可: 他のゲートウェイで使用されていない場合は、未使用の接続リソースをクリーンアップします。[gcloud] タブを使用して AgentConnectivityTemplate を削除し、ネットワーク アタッチメントを削除します。

gcloud

  1. Gemini Enterprise app または Agent Runtime エージェントがゲートウェイを参照していないことを確認します。Agent Gateway からワークロードの関連付けを解除するの手順に沿って操作します。

  2. 認可ポリシーと認可拡張機能を削除します。

    1. ゲートウェイのリージョン内の認可ポリシーを一覧表示して、target.resources フィールドでゲートウェイを参照しているポリシーを見つけ、参照されている authzExtensions をメモします。

      gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"

      LOCATION はゲートウェイのリージョンに、PROJECT_ID はプロジェクト ID に置き換えます。

    2. ゲートウェイをターゲットとする各 AuthzPolicy を削除します。

      gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      AUTHZ_POLICY_NAME は、ゲートウェイをターゲットとする各認可ポリシーの ID に置き換えます（例: コンソールで作成されたポリシーの場合は AGENT_GATEWAY_NAME-iap-authzpolicy または AGENT_GATEWAY_NAME-aisecurity-authzpolicy）。

    3. 省略可: 参照元の AuthzPolicy リソースを削除した後、他のポリシーで使用されていない AuthzExtension リソースを削除します。

      gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

      AUTHZ_EXTENSION_NAME は、未使用の認可拡張機能の ID に置き換えます。

  3. Agent Gateway を削除します。

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    AGENT_GATEWAY_NAME は、削除するゲートウェイの名前に置き換えます。

  4. ゲートウェイがリージョン ゲートウェイ リストに表示されなくなったことを確認します。

    gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

  5. 省略可: Agent Gateway が参照している AgentConnectivityTemplate は削除できません。ゲートウェイを削除したら、未使用の接続テンプレートを削除します。

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    CONNECTIVITY_TEMPLATE_NAME は、未使用の接続テンプレートの名前に置き換えます。基盤となる Private Service Connect ネットワーク アタッチメント、プライベート Cloud DNS ゾーン、Certificate Manager TrustConfig リソースが不要になった場合は、ネットワーク アタッチメントを削除するをご覧ください。

次のステップ

ガイド

Agent Gateway の認可を IAP、Model Armor、または独自のカスタム認可サービスに委任する方法について説明します。

ガイド

Agent Gateway をモニタリングする方法について説明します。

ガイド

Agent Gateway の設定方法を学習します。

トラブルシューティング

Agent Gateway の接続に関するトラブルシューティング方法について説明します。