將 Model Armor 與 Agent Gateway 整合

Gemini Enterprise Agent Platform 是用來建構及管理企業級 AI 代理的平台。Agent Gateway 是控制層，可管理、保護及控管 AI 代理程式在 Google Cloud 環境中，以及與外部代理程式、AI 應用程式和 LLM 的連線和互動方式。整合 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 僅支援使用 streamQuery 方法，對以 Agent Development Kit 建構的代理進行串流清除作業。
  • 跨專案使用範本：在一個專案中使用 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. 在您打算新增閘道的相同區域中，建立一或多個 Model Armor 範本。輸入和輸出流量可使用相同範本。

    記下範本名稱。如要在Google Cloud 控制台中複製範本名稱，請查看範本的詳細資料，然後按一下範本名稱旁的「複製到剪貼簿」圖示 。

  3. 在儲存 Model Armor 範本的相同區域中設定 Agent Gateway。針對「Client-to-Agent (ingress) gateway」，指定您為輸入流量建立的 Model Armor 範本。針對「Agent-to-Anywhere (egress) gateway」(代理程式至任何位置 (輸出) 閘道)，指定您為輸出流量建立的 Model Armor 範本。這兩種流量流程可使用相同範本。

  4. 將必要的 IAM 角色授予適當的服務代理：

    • 用戶端至代理 (輸入)：授予 AI Platform Reasoning Engine 服務代理下列角色：

      • AI 代理所屬專案中的 Model Armor Callout User (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。

    • 代理至任意目的地 (輸出)：將下列角色授予 Service Extensions 服務代理：

      • 在含有閘道的專案中，Model Armor Callout 使用者 (roles/modelarmor.calloutUser) 和服務使用情形用戶 (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」。

    如需授予角色的相關一般資訊，請參閱「授予單一身分與存取權管理角色」。

輸入和輸出流量

在 Agent Gateway 和 Model Armor 整合的脈絡中，輸入和輸出這兩個詞是從 AI 代理互動的角度來看：

  • 輸入流量 (用戶端到代理)：指用戶端與代理之間的通訊流程。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 則會根據結果允許或封鎖回覆。

代理至任意目的地 (輸出) 防護

您定義的範本會用於評估：

  • 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 資源要求路徑中採用的安全防護措施。

每項追蹤記錄都包含一或多個時距，其中每個時距 ID 代表追蹤記錄中的特定作業或工作單元。要求執行期間產生的記錄，會與執行作業的特定時距 ID 建立關聯。

追蹤記錄 ID 的處理方式有兩種：

  • 自動：啟用 Google Cloud Observability 時，Agent Gateway 會自動產生追蹤 ID，並透過系統傳播。

  • 使用者提供：您可以在要求中使用 traceparent HTTP 標頭，提供自己的追蹤 ID，藉此覆寫系統產生的追蹤 ID。

    以下程式碼範例說明如何在要求中將自訂追蹤 ID 傳遞至 streamQuery 方法：

    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：專案的 ID。 Google Cloud
    • REASONING_ENGINE_ID：推理引擎的 ID。

建議使用追蹤 ID，從呼叫端到 Agent Gateway，再到 Model Armor 和任何下游代理，端對端地關聯記錄和追蹤記錄。這對偵錯、瞭解安全性動作及監控效能至關重要。詳情請參閱「查看 Model Armor 追蹤範圍」。

如要查看特定追蹤 ID 的清除作業記錄，請在 Logs Explorer 中使用下列查詢：

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

將 TRACE_ID 替換為要求的追蹤 ID。

使用關聯性 ID

關聯 ID 會將 Cloud Logging 中與單一串流清除工作階段相關的所有記錄項目連結在一起，從初始要求到最終回應皆不例外。這是內部 ID，主要用於 Model Armor 記錄，特別是輸入串流工作階段。詳情請參閱「關聯記錄和相關事件」。