将 Model Armor 与 Agent Gateway 集成

Gemini Enterprise Agent Platform 是一个用于构建和管理企业级 AI 智能体的平台。Agent Gateway 充当控制平面，用于管理、保护和控制 AI 智能体 在环境内以及与外部 智能体、AI 应用和 LLM 的连接和互动方式。 Google Cloud 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 方法对使用智能体开发套件构建的智能体进行流式传输清理。
  • 跨项目模板使用：在一个项目中使用 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。对于客户端到代理 （入站流量） 网关， 请指定您为入站流量创建的 Model Armor 模板。 对于 代理到任意目的地（出站流量） 网关， 请指定您为出站 流量创建的 Model Armor 模板。您可以对这两种流量使用同一模板。

  4. 向相应的服务账号授予所需的 IAM 角色：

    • 客户端到代理（入站流量）：向 AI Platform Reasoning Engine Service Agent 服务帐号授予以下角色：

      • 包含 AI 智能体的项目中的 Model Armor Callout User (roles/modelarmor.calloutUser) 角色。

      • 包含 Model Armor 模板的项目中的 Model Armor User (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 User (roles/modelarmor.calloutUser) 和 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) 角色。
      • 包含 Model Armor 模板的项目中的 Model Armor User (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 使用智能体开发套件 (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 会连接单个请求在分布式系统中跨多个服务传输时的所有事件。这包括 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 中与单个流式清理会话相关的所有日志条目（从初始请求到最终回答）关联在一起。它是一个主要在 Model Armor 日志中使用的内部标识符，专门用于入站流式会话。 如需了解详情，请参阅关联日志和相关 事件。