Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

将 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 方法对通过智能体开发套件构建的智能体进行流式传输清理。
跨项目使用模板：在一个项目中使用 Model Armor 模板来清理另一个项目（例如 Agent Gateway）中服务的请求时，托管模板的项目和托管调用服务的项目都需要有足够的 Model Armor API 配额。如需了解详情，请参阅管理配额。
区域对齐：Model Armor 及其集成的服务必须部署在同一 Google Cloud 区域中。不支持对 Model Armor 进行跨区域调用。
出站流量集成兼容性：Model Armor 对出站流量的内嵌保护仅限于与 MCP 服务器、遵循 OpenAI 格式的服务以及通过智能体网关进行的 A2A 集成。
Ingress 集成兼容性：Model Armor 内嵌 Ingress 保护功能仅支持使用 ADK 构建的代理。

在网关上配置 Model Armor

如需在网关上配置 Model Armor，请按以下步骤操作：

在要创建 Model Armor 模板的项目中启用 Model Armor API。
在您计划添加网关的同一区域中创建一个或多个 Model Armor 模板。您可以对入站流量和出站流量使用同一模板。

记下模板名称。如需在Google Cloud 控制台中复制模板的名称，请查看模板的详细信息，然后点击模板名称旁边的 复制到剪贴板。
在存储 Model Armor 模板的同一区域中设置 Agent Gateway。对于客户端到代理（入站）网关，请指定您为入站流量创建的 Model Armor 模板。对于代理到任意位置（出站）网关，请指定您为出站流量创建的 Model Armor 模板。您可以为这两个流量流使用同一模板。
向相应的服务代理授予所需的 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. \
    --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. \
    --role=roles/modelarmor.user
```
  替换以下内容：
  - AGENT_RUNTIME_PROJECT_ID：您在其中创建了代理的项目的 ID。
  - AGENT_RUNTIME_PROJECT_NUMBER：您在其中创建代理的项目编号。
  - MODEL_ARMOR_PROJECT_ID：包含 Model Armor 模板的项目的项目 ID。
- 代理到任意位置（出站）：向服务扩展服务代理授予以下角色：
  - 在包含网关的项目中，拥有 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. \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --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 仅净化使用智能体开发套件 (ADK) 构建且在 Agent Runtime 上运行的代理的 reasoningEngines.streamQuery 请求和响应。

所有其他 ReasoningEngine载荷和 ReasoningEngine 错误响应都不会发送到 Model Armor。非 ADK 载荷（例如 Langchain 载荷）也不会发送到 Model Armor。

客户端到代理的流量流

客户端向智能体发送提示。Agent Gateway 会拦截请求并将载荷发送到 Model Armor。
Model Armor 会筛查请求。如果被屏蔽，客户端会收到错误。
如果允许，请求会到达 AI 智能体。
AI 智能体可生成回复。Agent Gateway 会在该响应到达客户端之前拦截它。
Model Armor 会过滤回答，然后 Agent Gateway 会根据过滤结果允许或阻止该回答。

代理到任意目的地（出站流量）保护

您可以定义 Model Armor 用于评估的模板：

AI 智能体向外部系统发出的出站请求。
从外部系统返回到 AI 智能体的传入响应。

此保护措施适用于与以下系统的通信：

外部 LLM 和第三方 AI 智能体
Model Context Protocol (MCP) 服务器
其他 AI 智能体

代理到任意目的地的流量流

AI 智能体向外部系统发起请求。Agent Gateway 会拦截出站流量。
Model Armor 会过滤传出的载荷。如果被屏蔽，连接会终止。
如果允许，则将请求发送到外部系统。
外部系统会发回响应。Agent Gateway 会拦截此传入的响应。
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 并通过系统传播该 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。

建议使用 trace 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 日志中使用，特别是对于入站流式会话。如需了解详情，请参阅关联日志和相关事件。

将 Model Armor 与 Agent Gateway 集成 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

限制