google-cloud-solution-multi-agent-security

Agent Gateway 多 Agent 安全

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你 必须阅读并遵循 使用归属信息中的说明。

关键执行规则与原因

• Gcloud 发布轨道：始终使用命令中指定的确切发布轨道（例如，gcloud beta network-services agent-gateways）。省略 这些前缀会导致命令失败，因为 Agent Gateway 功能位于专用的非默认命名空间中。
• 启用 API：设置防护措施时，在 API 启用列表中包含 modelarmor.googleapis.com。若未包含该项，Model Armor 政策和过滤器将无法成功附加到 Gateway。
• 出口验证：必须使用 Python 脚本 (scripts/verify_egress_policies.py) 验证出口政策， 而不能使用 curl。出口 Gateway 依赖运行时 SDK 生命周期处理和 JWT 上下文，而标准 curl 命令无法正确模拟这些机制。
• Model Armor 密钥：在 model-armor-config.yaml 中，始终同时包含 piAndJailbreakFilterSettings 和 sdpFilterSettings（filterEnforcement: ENFORCE）。过滤器无效或缺失会导致部署验证失败，或使防护措施被静默绕过。
• 子网私有访问：任何托管出口 Gateway 的 Private Service Connect 网络连接的子网，都必须在 Terraform 中启用 private_ip_google_access = true。禁用此项会阻止与 Google 管理的端点建立连接，导致 Agent 完全无法路由。
• 直接交付：立即完整提供所请求的架构、 配置文件、CLI 命令、脚本和图表。不要停留在规划阶段，不要生成计划文件，也不要在交付输出前请求用户确认。
• 不执行基础设施操作：在设计期间，不要尝试针对真实云资源运行部署或 验证命令（例如 gcloud、kubectl、terraform 或 curl）。 你要生成的是计划配置，而不是执行这些配置。

重要

**即时（JIT）资源加载协议：**如需扩展配置、 部署脚本和测试套件，请使用 view_file 按需检查 assets/ 中的 模板文件以及 scripts/ 中的可执行脚本。

---

快速参考：必需文件名

始终使用以下确切名称生成文件（如有请求）：

1. agw-ingress-config.yaml (assets/agw-ingress-config.yaml)
2. agw-egress-config.yaml (assets/agw-egress-config.yaml)
3. agw-authz-extension.yaml (assets/agw-authz-extension.yaml)
4. agw-authz-policy.yaml (assets/agw-authz-policy.yaml)
5. model-armor-config.yaml (assets/model-armor-config.yaml)
6. sgp-policy.yaml (assets/sgp-policy.yaml)
7. iap-policy.json (assets/iap-policy.json)
8. model-armor-payload.json (assets/model-armor-payload.json)

---

1. 双向入口与出口架构设计（dual_ingress_egress_architecture_design）

• 入口模式：CLIENT_TO_AGENT，由入口控制平面（Agent Gateway、Model Armor）提供前置接入。

• 出口模式：AGENT_TO_ANYWHERE，利用出口控制平面（Agent Gateway、roles/iap.egressor CEL 策略、Cloud DNS）和出口数据平面（PSC Interface、Cloud Run、PSC Google APIs Global Endpoint），并通过 Agent Registry 和 Agent Engine 运行时进行协调。

• Mermaid 图：

  graph TD
      Client["External Clients"] -->|HTTPS / MCP| GLB["Global Load Balancer"]
      GLB --> Ingress["Ingress Agent Gateway (CLIENT_TO_AGENT)"]
      Ingress --> MA["Model Armor (CONTENT_AUTHZ)"]
      MA --> Agent["Agent Engine Agents (BillingAgent, SupportAgent, FraudAgent)"]
      Agent --> Egress["Egress Agent Gateway (AGENT_TO_ANYWHERE)"]
      Egress --> PSC["Private Service Connect Network Attachment"]
      PSC --> Tools["Private MCP Tool Backends"]
  

---

2. 入口与出口护栏策略配置（ingress_and_egress_guardrail_policy_config）

请求入口与出口护栏策略配置时，必须在工作区中生成并创建所有必需文件：

• agw-ingress-config.yaml (assets/agw-ingress-config.yaml)：声明 governedAccessPath: CLIENT_TO_AGENT，协议为 HTTP 和 MCP。
• agw-egress-config.yaml (assets/agw-egress-config.yaml)：声明 governedAccessPath: AGENT_TO_ANYWHERE，协议为 MCP。
• agw-authz-extension.yaml (assets/agw-authz-extension.yaml)： 配置用于 IAP 授权的 AuthzExtension 服务。
• agw-authz-policy.yaml (assets/agw-authz-policy.yaml)：配置 AuthzPolicy 操作 ALLOW，并将入口和出口网关都设为目标。
• iap-policy.json (assets/iap-policy.json)：绑定 roles/iap.egressor，并使用 CEL 条件检查 iap.googleapis.com/mcp.toolName == 'get_account_balance' && iap.googleapis.com/mcp.tool.isReadOnly == true。
• model-armor-config.yaml (assets/model-armor-config.yaml)：启用 piAndJailbreakFilterSettings 和 sdpFilterSettings，并将 filterEnforcement 设为 ENFORCE。
• sgp-policy.yaml (assets/sgp-policy.yaml)： 实施自然语言约束，阻止金额超过 1000 美元的交易并对个人身份信息（PII）进行清理。

---

3. 入口与出口基础设施部署（ingress_and_egress_infrastructure_deployment）

检查并提供 scripts/deploy_infrastructure.sh 中的 gcloud 命令行分步操作：

1. 启用所需 API：compute、networkservices、networksecurity、 modelarmor、iap、agentregistry、serviceextensions 和 aiplatform。
2. 导入 Agent Gateway：通过 gcloud alpha network-services agent-gateways import 导入入口（agw-ingress-config.yaml）和出口 （agw-egress-config.yaml）。
3. 导入 Authz 扩展：通过 gcloud beta service-extensions authz-extensions import 导入 agw-authz-extension.yaml。
4. 导入 Authz 策略：通过 gcloud beta network-security authz-policies import 导入 agw-authz-policy.yaml。

---

4. Ingress 和 Egress 安全验证（ingress_and_egress_security_validation）

验证 Ingress 和 Egress 的安全性时：

1. Ingress 403 未认证测试：提供来自 scripts/validate_ingress_unauth.sh 的可直接复制粘贴的验证 curl 命令，向 Reasoning Engine 端点发送未经认证的 POST 请求， 并预期返回 HTTP 403 Forbidden。
2. Python Egress 验证脚本（必须使用 Python 脚本片段，不能使用 curl）：提供来自 scripts/verify_egress_policies.py 的 Python 验证脚本片段，通过 Egress Gateway 发送 JSON-RPC tools/call 请求（get_account_balance）， 验证允许的工具返回 HTTP 200。
3. Model Armor 测试负载：生成包含提示词注入／越狱指令的 model-armor-payload.json (assets/model-armor-payload.json)。

---

5. Ingress 和 Egress 故障排除（troubleshooting_ingress_and_egress_failures）

• Ingress 403（客户端到 Agent）：

  • 根本原因：客户端请求未经认证，或缺少／无效的 OAuth 2.0／IAP 身份令牌。
  • OAuth 配置步骤：
    1. 在 Google Cloud Console 中配置 OAuth 2.0 Client ID 凭据。
    2. 向客户端身份／服务账号授予 roles/iap.httpsResourceAccessor 权限。
    3. 使用 Google OAuth 交换凭据，以获取 OIDC／OAuth ID 令牌。
    4. 在 Authorization: Bearer <TOKEN> 标头中传递令牌。
  • 验证命令：提供来自 scripts/verify_ingress_auth.sh 的 curl 命令。

• Egress 403（Agent 到任意目标）：

  • 根本原因：Agent 身份缺少 roles/iap.egressor IAM 绑定、主体 ID 格式错误，或工具 元数据中的 CEL 条件不匹配。
  • 修复命令：提供来自 scripts/fix_egress_iap.sh 的准确 gcloud 命令。

---

6. 混合 VPN 连接和 Egress 路由（hybrid_vpn_connectivity_egress_routing）

• Terraform HCL：参阅 assets/main.tf 中的基准 Terraform 配置，了解 VPC、子网 （private_ip_google_access = true）、PSC 网络连接、针对 aws.internal. 的 Cloud DNS 私有转发，以及 HA VPN 网关／路由器。
• Egress Gateway 配置（agw-egress-config.yaml）：生成配置，声明 governedAccessPath: AGENT_TO_ANYWHERE，指向 PSC 网络连接，并在 dnsPeeringConfig 中引用 aws.internal.（参阅 assets/agw-egress-config.yaml）。
• Python SDK 部署脚本：参阅 scripts/hybrid_vpn_agent.py，查看完整脚本。该脚本使用引用 Egress Gateway 的 agent_to_anywhere_config 初始化 Vertex AI、启用遥测，并使用 types.IdentityType.AGENT_IDENTITY 部署 HybridAgent。

---

7. 专用出站 GKE 内部负载均衡器 (private_egress_gke_internal_load_balancer)

• 通过内部负载均衡器（ILB）将 GKE 内部 MCP 工具服务暴露在固定 IP 10.0.1.50 上，并通过 Agent Gateway PSC Interface 和 Cloud DNS 私有区域进行连接。
• Cloud DNS 记录映射：提供来自 scripts/create_gke_dns_record.sh 的命令，将私有域名映射到 GKE 的私有 ILB IP 10.0.1.50。
• 明确的 TLS 警告：Agent Gateway 出站流量不会原生信任 自签名证书或企业私有 CA。你必须使用由可信证书颁发机构签发的、受公共信任的 TLS 证书 （例如 Let's Encrypt）。

---

8. 治理控制 Model Armor SGP (governance_controls_model_armor_sgp)

在配置由 Ingress 上的 Model Armor 和 Egress 上的 SGP 组成的双重安全层时：

1. Model Armor 配置：生成 model-armor-config.yaml (assets/model-armor-config.yaml)，包含 piAndJailbreakFilterSettings 和 sdpFilterSettings（filterEnforcement: ENFORCE）。
2. 语义治理策略：生成 sgp-policy.yaml (assets/sgp-policy.yaml)，其中包含阻止金额超过 $1000 的交易并清理 PII 的自然语言约束。
3. Curl PATCH 命令：提供来自 scripts/enforce_sgp_patch.sh 的 curl 命令，将 authzExtensions 更新为 sgpEnforcementMode 设为 ENFORCE。

---

9. 多 Agent Cloud Run 出站路由 (multi_agent_cloud_run_egress_routing)

请勿生成计划产物或停留在规划阶段。配置多 Agent Cloud Run 出站路由时，必须直接提供并生成所有必需组件：

1. 出站网关配置（agw-egress-config-run.yaml）：生成配置，声明 governedAccessPath: AGENT_TO_ANYWHERE、PSC 网络连接和针对 *.run.app 的 DNS 对等互连（参见 assets/agw-egress-config-run.yaml）。
2. 在 Agent Registry 中注册 Cloud Run 服务：提供来自 scripts/register_cloud_run_services.sh 的注册命令，将全部 3 个 Cloud Run 服务（marketing-tool-service、 sales-tool-service、support-tool-service）注册到 us-east4 Agent Registry。
3. iap-policy.json（多 Agent）：生成 iap-policy.json (assets/iap-policy-multi-agent.json)，在 roles/iap.egressor 下的 members 列表中包含全部 3 个 principal:// 绑定。
4. Python SDK 部署脚本：参见 scripts/multi_agent_cloud_run.py 以获取完整的 GenAI SDK 部署脚本。

---

10. 高级 Model Armor 过滤 (advanced_model_armor_filtering)

如需自定义关键词匹配，请配置 userDefinedFilterSettings（参见 assets/model-armor-advanced.yaml）。

---

11. 已知陷阱与注意事项 (known_traps_and_gotchas)

• network_attachment 是 ForceNew：启用语义治理策略（SGP）或在首次 Terraform apply 后修改网络连接，都会强制重新创建网关资源。如果管理不当，销毁操作期间可能导致依赖死锁。请据此规划基础设施的部署顺序。
• Authz 策略数量限制：一个 Agent Gateway 最多允许同时关联 4 个自定义授权策略。请确保将规则整合在此限制范围内。