Model Armor と Agent Gateway を統合する

Gemini Enterprise Agent Platform は、エンタープライズ グレードの AI エージェントを構築して管理するためのプラットフォームです。Agent Gateway は、 Google Cloud 環境内および外部のエージェント、AI アプリケーション、LLM との AI エージェントの接続とやり取りの方法を管理、保護、制御するコントロール プレーンとして機能します。Model Armor と Agent Gateway の統合により、Model Armor のスクリーニング機能が Gemini Enterprise Agent Platform が管理する通信経路に直接組み込まれます。コンテンツが Agent Gateway を通過すると、Model Armor が呼び出され、事前定義されたセキュリティ テンプレートが適用されます。ポリシーに違反するコンテンツをブロックして編集するか、コンテンツを検査して検出された違反をログに記録するだけにするようにテンプレートを構成できます。これにより、プロンプト インジェクション、ジェイルブレイク、有害なコンテンツへの露出、センシティブ データ漏洩などのリスクを軽減できます。

Model Armor は、Agent Gateway を通過するコンテンツでポリシー違反を検出すると、これらのイベントをログに記録するように構成できます。これらの検出結果は、 Google Cloud コンソールの [Model Armor] ページで確認できます（Model Armor に移動）。これらの検出結果は Security Command Center にも表示されます。詳細については、Google Cloud コンソールで検出結果を確認するをご覧ください。

リアルタイム ストリーミング モードを使用する場合、Model Armor はストリーム内のトークン数を無制限にサポートしているため、長時間実行されるインタラクションやモデル レスポンスに適しています。

制限事項

Model Armor を Agent Gateway と統合する場合は、次の制限事項を考慮してください。

  • エージェントのストリーミング サポート: Model Armor は、Agent Development Kit で構築されたエージェントの streamQuery メソッドを使用したストリーミング サニタイズのみをサポートします。
  • プロジェクト間のテンプレートの使用: あるプロジェクトの Model Armor テンプレートを使用して、別のプロジェクトの Agent Gateway などのサービスのリクエストをサニタイズする場合、Model Armor の API 割り当ては、テンプレートをホストするプロジェクトと呼び出しサービスをホストするプロジェクトの両方で十分である必要があります。詳細については、割り当ての管理をご覧ください。
  • リージョン整合性: Model Armor と統合するサービスは、同じ Google Cloud リージョン内にデプロイする必要があります。Model Armor へのクロスリージョン呼び出しはサポートされていません。
  • 下り（外向き）統合の互換性: 下り（外向き）トラフィックに対する Model Armor のインライン保護は、MCP サーバー、OpenAI 形式に準拠するサービス、Agent Gateway を介した A2A との統合に限定されます。
  • 上り（内向き）統合の互換性: Model Armor を使用したインライン上り（内向き）保護は、ADK を使用してビルドされたエージェントでのみサポートされます。

ゲートウェイで Model Armor を構成する

ゲートウェイで Model Armor を構成する手順は次のとおりです。

  1. Model Armor テンプレートを作成するプロジェクトで、Model Armor API を有効にします。

  2. ゲートウェイを追加する予定のリージョンに、1 つ以上の Model Armor テンプレートを作成します。上り（内向き）トラフィックと下り（外向き）トラフィックの両方に同じテンプレートを使用できます。

    テンプレート名をメモします。Google Cloud コンソールでテンプレートの名前をコピーするには、テンプレートの詳細を表示し、テンプレート名の横にある [クリップボードにコピー] をクリックします。

  3. Model Armor テンプレートが保存されているリージョンと同じリージョンに Agent Gateway を設定します。[クライアントからエージェント（上り）ゲートウェイ] で、上り（内向き）トラフィック用に作成した Model Armor テンプレートを指定します。エージェントから任意の場所への（下り）ゲートウェイには、下り（外向き）トラフィック用に作成した Model Armor テンプレートを指定します。両方のトラフィック フローに同じテンプレートを使用できます。

  4. 適切なサービス エージェントに必要な IAM ロールを付与します。

    • クライアントからエージェントへ（内向き）: AI Platform Reasoning Engine サービス エージェントに次のロールを付与します。

      • AI エージェントを含むプロジェクトの Model Armor Callout ユーザー（roles/modelarmor.calloutUser）ロール。

      • Model Armor テンプレートを含むプロジェクトの Model Armor ユーザー（roles/modelarmor.user）ロール。

      gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

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

      • AGENT_RUNTIME_PROJECT_ID: エージェントを作成したプロジェクトのプロジェクト ID。
      • AGENT_RUNTIME_PROJECT_NUMBER: エージェントを作成したプロジェクトのプロジェクト番号。
      • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクトのプロジェクト ID。

    • エージェントから Anywhere へのアクセス（下り）: Service Extensions サービス エージェントに次のロールを付与します。

      • ゲートウェイを含むプロジェクトの Model Armor Callout ユーザー（roles/modelarmor.calloutUser）ロールと Service Usage コンシューマー（roles/serviceusage.serviceUsageConsumer）ロール。
      • Model Armor テンプレートを含むプロジェクトの Model Armor ユーザー（roles/modelarmor.user）ロール。
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

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

      • GATEWAY_PROJECT_ID: ゲートウェイを作成したプロジェクトのプロジェクト ID。
      • GATEWAY_PROJECT_NUMBER: ゲートウェイを作成したプロジェクトのプロジェクト番号。
      • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクトのプロジェクト ID。

      手順については、Model Armor に認可を委任するをご覧ください。

    ロールを付与する方法の一般的な情報については、単一の IAM ロールを付与するをご覧ください。

上り（内向き）トラフィックと下り（外向き）トラフィック

Agent Gateway と Model Armor の統合のコンテキストでは、上り（内向き）と下り（外向き）という用語は、AI エージェントのインタラクションの観点から使用されます。

  • 内向きトラフィック（クライアントからエージェント）: クライアントとエージェント間の通信フローを指します。Model Armor は、クライアントからエージェントへの受信リクエストと、エージェントからクライアントへの送信レスポンスの両方を保護できます。
  • 下り（外向き）トラフィック（エージェントから任意の場所）: エージェントと外部システム間の通信フローを指します。Model Armor は、エージェントから外部システムへのアウトバウンド リクエストと、外部システムからエージェントへのインバウンド レスポンスの両方を保護できます。

クライアントからエージェントへの（内向き）保護

Model Armor が評価に使用するテンプレートを定義します。

  • クライアント（エンドユーザーまたは呼び出しアプリケーション）から AI エージェントへの受信リクエスト。
  • AI エージェントからクライアントへの送信レスポンス。

単一のテンプレートを両方向に適用することも、各方向に異なるテンプレートを構成することもできます。

ADK プロトコルを使用するクライアントからエージェントへの（上り）トラフィックの場合、Model Armor は、Agent Development Kit（ADK）を使用して構築され、Agent Runtime で実行されているエージェントの reasoningEngines.streamQuery リクエストとレスポンスのみをサニタイズします。

他のすべての ReasoningEngine ペイロードと ReasoningEngine エラー レスポンスは Model Armor に送信されません。ADK 以外のペイロード（Langchain ペイロードなど）も Model Armor に送信されません。

クライアントからエージェントへのトラフィック フロー

  1. クライアントがエージェントにプロンプトを送信します。Agent Gateway がリクエストをインターセプトし、ペイロードを Model Armor に送信します。
  2. Model Armor はリクエストをスクリーニングします。ブロックされている場合、クライアントはエラーを受け取ります。
  3. 許可されると、リクエストは AI エージェントに到達します。
  4. AI エージェントが回答を生成します。Agent Gateway は、このレスポンスがクライアントに到達する前にインターセプトします。
  5. Model Armor はレスポンスをスクリーニングし、Agent Gateway は判定に基づいてレスポンスを許可またはブロックします。

エージェントから任意の宛先へ（外向き）の保護

Model Armor が評価に使用するテンプレートを定義します。

  • AI エージェントから外部システムへの送信リクエスト。
  • 外部システムから AI エージェントに返されるレスポンス。

この保護は、次のようなシステムとの通信に適用されます。

  • 外部 LLM とサードパーティの AI エージェント
  • Model Context Protocol（MCP）サーバー
  • その他の AI エージェント

エージェントから任意の宛先へのトラフィック フロー

  1. AI エージェントが外部システムへのリクエストを開始します。Agent Gateway が送信トラフィックをインターセプトします。
  2. Model Armor は送信ペイロードをスクリーニングします。ブロックされている場合、接続は終了します。
  3. 許可されている場合、リクエストは外部システムに送信されます。
  4. 外部システムがレスポンスを返します。Agent Gateway は、この受信レスポンスをインターセプトします。
  5. Model Armor はレスポンス ペイロードをスクリーニングし、Agent Gateway はエージェントに到達することを許可するか、ブロックします。

詳細については、ゲートウェイで Model Armor を構成するをご覧ください。

ストリーミング リクエストを追跡してデバッグする

ストリーミング リクエストのトラッキングとデバッグを容易にするため、Model Armor は相関 ID とトレース ID を使用します。

トレース ID を使用する

トレース ID は、分散システム内の複数のサービスを通過する単一のリクエストのすべてのイベントを接続します。これには、Model Armor が Agent Gateway リソースのリクエスト パス内で適用するセキュリティ強制が含まれます。

各トレースには 1 つ以上のスパンが含まれます。各スパン ID は、トレース内の特定のオペレーションまたは作業単位を表します。リクエストの実行中に生成されたログは、作業を実行するオペレーションの特定のスパン ID に関連付けられます。

トレース ID は次の 2 つの方法で処理されます。

  • 自動: Google Cloud Observability が有効になっている場合、Agent Gateway はトレース ID を自動的に生成し、システム全体に伝播します。

  • ユーザー指定: リクエストで traceparent HTTP ヘッダーを使用して独自のトレース ID を指定することで、システム生成のトレース ID をオーバーライドできます。

    次のコードサンプルは、streamQuery メソッドへのリクエストでカスタム トレース ID を渡す方法を示しています。

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-98adffecc8dd095968a06c44216190f6-5b565a8342378cd7-01" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:streamQuery?alt=sse"

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

    • LOCATION: 推論エンジンが配置されているリージョン。
    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • REASONING_ENGINE_ID: 推論エンジンの ID。

トレース ID を使用すると、呼び出し元から Agent Gateway、Model Armor、ダウンストリーム エージェントまで、ログとトレースをエンドツーエンドで関連付けることができます。これは、デバッグ、セキュリティ アクションの把握、パフォーマンスのモニタリングに不可欠です。詳細については、Model Armor トレース スパンを表示するをご覧ください。

特定のトレース ID のサニタイズ オペレーション ログを表示するには、ログ エクスプローラで次のクエリを使用します。

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID

TRACE_ID は、リクエストのトレース ID に置き換えます。

相関 ID を使用する

相関 ID は、最初の要求から最終的なレスポンスまで、単一のストリーミング サニタイズ セッションに関連する Cloud Logging のすべてのログエントリをリンクします。これは、主に Model Armor ログ内で使用される内部 ID で、特に上り（内向き）ストリーミング セッションに使用されます。詳細については、ログと関連イベントを関連付けるをご覧ください。