將 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 的整合。
• Ingress 整合相容性：Model Armor 的內嵌輸入防護功能僅支援使用 ADK 建構的代理。
• 不支援文件：這項整合功能不支援清理含有文件或上傳檔案 (例如 PDF) 的提示和回覆。如要篩選文件，請直接呼叫 Model Armor REST API。
• 支援的酬載：如需支援的酬載清單，請參閱本文件中的「支援和不支援的酬載」一節。

在閘道設定 Model Armor

如要在閘道上設定 Model Armor，請按照下列步驟操作：

1. 在要建立 Model Armor 範本的專案中，啟用 Model Armor API。

2. 在您打算新增閘道的區域，建立一或多個 Model Armor 範本。您可以將同一個範本用於輸入和輸出流量。

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

   如果您在不同專案中建立 Model Armor 範本，而該專案包含 AI 代理或 Agent Gateway，且您使用 VPC Service Controls，則這兩個專案必須位於相同的 VPC Service Controls 服務範圍。

3. 在儲存 Model Armor 範本的區域設定 Agent Gateway。在「Client-to-Agent (ingress) gateway」(用戶端至代理 (輸入) 閘道) 部分，指定您為輸入流量建立的 Model Armor 範本。在「Agent-to-Anywhere (egress) gateway」(代理至任何位置 (輸出) 閘道) 部分，指定您為輸出流量建立的 Model Armor 範本。兩個流量方向可使用相同範本。

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

   • 用戶端至代理 (輸入)：將下列角色授予 AI 平台推論引擎服務代理：

     • 在含有 AI 代理的專案中，具備 Model Armor 呼叫使用者 (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 呼叫使用者 (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」。

   如要瞭解如何授予角色，請參閱「授予單一 IAM 角色」。

輸入和輸出流量

在整合 Agent Gateway 和 Model Armor 時，「輸入」和「輸出」這兩個詞彙是從 AI 代理互動的角度來使用：

• 輸入流量 (用戶端到代理)：指用戶端與代理之間的通訊流程。Model Armor 可保護從用戶端傳送至代理的傳入要求，以及從代理傳回用戶端的傳出回覆。
• 輸出流量 (代理到任何位置)：指代理與外部系統之間的通訊流程。Model Armor 可保護代理傳送至外部系統的傳出要求，以及外部系統傳回代理的傳入回覆。

用戶端至代理 (輸入) 防護

您可以定義範本，讓 Model Armor 用於評估：

• 用戶端 (使用者或呼叫應用程式) 傳送至 AI 代理的傳入要求。
• AI 代理傳回用戶端的回應。

您可以將單一範本套用至兩個方向，也可以為每個方向設定不同的範本。

用戶端至代理的流量

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

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

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

• 自動：啟用 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 追蹤記錄 span」。

如要查看特定追蹤 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 記錄，特別是輸入串流工作階段。詳情請參閱「建立記錄與相關事件的關聯」。

支援和不支援的酬載

本節列出 Model Armor 清理的酬載類型。

用戶端至代理 (輸入) 流量

對於使用 ADK 通訊協定的用戶端到代理 (輸入) 流量，Model Armor 只會清理 reasoningEngines.streamQuery 要求和回應，這些要求和回應是針對使用 Agent Development Kit (ADK) 建構並在 Agent Runtime 上執行的代理。

所有其他 ReasoningEngine 酬載和 ReasoningEngine 錯誤回應都不會傳送至 Model Armor。非 ADK 酬載 (例如 Langchain 酬載) 也不會傳送至 Model Armor。

代理至任意目的地 (輸出) 流量

代理程式對任何位置 (輸出) 的流量支援下列酬載。

A2A 酬載

Model Armor 只會清理 A2A v1 通訊協定的下列酬載：

• 傳送訊息作業
• 代理資訊卡
• Get Extended Agent Card 作業
• JSON-RPC 通訊協定繫結
• HTTP+JSON/REST 通訊協定繫結

Model Armor 允許下列 A2A 酬載，不需經過清理：

• 來自 A2A 1.0 版以前版本的酬載
• SendStreamingMessage
• GetTask
• ListTasks
• CancelTask
• SubscribeToTask
• CRUD methods on TaskPushNotificationConfig
• 使用 A2A gRPC 通訊協定繫結 (透過網路傳輸的 protobuf) 的酬載
• A2A 錯誤酬載

MCP 酬載

Model Armor 只會清理下列 MCP 酬載：

• tools/call 要求和回應
• prompts/get 要求和回應
• MCP 工具執行錯誤 (惡意 MCP 工具作者的提示詞注入目標)

Model Armor 允許下列酬載，不需經過清理：

• tools/list
• resources/*
• notifications/*
• MCP 適用的可串流 HTTP/SSE
• MCP 通訊協定錯誤 (例如工具執行錯誤以外的所有錯誤)

外部 LLM 酬載

Model Armor 只會清理 OpenAI API 通訊協定 (輸出) 的下列酬載，包括 openai.com 上的 GPT 模型，以及透過 OpenAI API 相容 LLM 伺服器 (例如 vLLM) 提供的任何其他模型。未列於此處的酬載則不需經過清理。

• Chat completions： 建立、刪除、取得、列出及更新 (僅限非串流變體)
• 取得即時通訊訊息
• Responses：建立、取得和刪除 (僅限非串流變體)
• OpenAI API 錯誤 (包括 vLLM 的變體)
• Legacy Completions
• 舊版助理：建立、刪除、列出、修改及擷取
• 舊版訊息：建立、刪除、列出、修改及擷取
• 舊版討論串：建立、刪除、修改及擷取
• 嵌入：建立