Model Armor と Agent Gateway を統合する

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

Model Armor は、Agent Gateway を通過するコンテンツでポリシー違反を検出すると、これらのイベントをログに記録するように構成できます。これらの検出結果は、 コンソールの [Model Armor] ページで確認できます（[Go to Model Armor]）。 Google Cloud これらの検出結果は、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 API を Model Armor テンプレートを作成するプロジェクトで有効にします。

  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。

    • エージェントから任意の宛先へ（下り（外向き））: Agent Gateway サービス アカウントに次のロールを付与します。

      • ゲートウェイを含むプロジェクトの 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 は、 reasoningEngines.streamQuery Agent Development Kit（ADK）を使用して構築され、Agent Runtime で実行されているエージェントの リクエストとレスポンスのみをサニタイズします。

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

各トレースには 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 であり、特に上り（内向き）ストリーミング セッションで使用されます。 詳細については、ログと関連 イベントを関連付けるをご覧ください。