在 Google Cloud 上设计多智能体 Agent…

当需要为 Google Cloud Agent Gateway 配置多智能体安全（入站 CLIENT_TO_AGENT、出站 AGENT_TO_ANYWHERE，涉及 Model Armor、IAP、Agent Registry）时，按此做法生成配置、部署命令与验证脚本。

适用场景

解决思路

1. 使用精确的 gcloud 发布轨道前缀（如 `gcloud beta network-services agent-gateways`），因为 Agent Gateway 功能位于非默认命名空间，省略前缀会导致命令失败。
2. 在启用 API 列表中加入 `modelarmor.googleapis.com`，否则 Model Armor 策略和过滤器无法成功挂载到 Gateway。
3. 出站策略验证必须使用 Python 脚本（scripts/verify_egress_policies.py），不能用 curl；出站网关依赖运行时 SDK 生命周期处理和 JWT 上下文，curl 无法正确模拟。
4. 在 `model-armor-config.yaml` 中始终同时包含 `piAndJailbreakFilterSettings` 和 `sdpFilterSettings`（`filterEnforcement: ENFORCE`），过滤器无效或缺失会导致部署校验失败或静默绕过防护。
5. 任何承载出站网关 Private Service Connect 网络附件的子网，必须在 Terraform 中启用 `private_ip_google_access = true`，否则会阻断到 Google 托管端点的连接，导致智能体路由完全失败。
6. 直接完整交付所请求的架构、配置文件、CLI 命令、脚本和图表，不要停在规划阶段、不要生成计划工件、不要在交付前请求用户确认。
7. 设计阶段不要对真实云资源执行部署或验证命令（如 gcloud、kubectl、terraform、curl），只生成计划配置。
8. 按需使用 `view_file` 检查 assets/ 中的模板文件和 scripts/ 中的可执行脚本，以获取扩展配置、部署脚本和测试套件。
9. 生成文件时使用精确文件名：`agw-ingress-config.yaml`、`agw-egress-config.yaml`、`agw-authz-extension.yaml`、`agw-authz-policy.yaml`、`model-armor-config.yaml`、`sgp-policy.yaml`、`iap-policy.json`、`model-armor-payload.json`。
10. 设计双入站/出站架构：入站模式 `CLIENT_TO_AGENT` 由 Ingress Control Plane（Agent Gateway、Model Armor）前置；出站模式 `AGENT_TO_ANYWHERE` 使用 Egress Control Plane（Agent Gateway、`roles/iap.egressor` CEL 策略、Cloud DNS）和 Egress Data Plane（PSC Interface、Cloud Run、PSC Google APIs Global Endpoint），通过 Agent Registry 和 Agent Engine 运行时协调。
11. 生成入站/出站护栏策略配置：`agw-ingress-config.yaml` 声明 `governedAccessPath: CLIENT_TO_AGENT` 及协议 HTTP 和 MCP；`agw-egress-config.yaml` 声明 `governedAccessPath: AGENT_TO_ANYWHERE` 及协议 MCP；`agw-authz-extension.yaml` 配置 IAP 授权的 AuthzExtension 服务；`agw-authz-policy.yaml` 配置 `AuthzPolicy` 动作 `ALLOW` 同时作用于入站和出站网关；`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` 启用 `piAndJailbreakFilterSettings` 和 `sdpFilterSettings`（`filterEnforcement: ENFORCE`）；`sgp-policy.yaml` 实现自然语言约束，阻止超过 $1000 的交易并脱敏 PII。
12. 按 scripts/deploy_infrastructure.sh 提供分步 gcloud CLI 命令：1) 启用 API：`compute`、`networkservices`、`networksecurity`、`modelarmor`、`iap`、`agentregistry`、`serviceextensions`、`aiplatform`；2) 通过 `gcloud alpha network-services agent-gateways import` 导入入站（`agw-ingress-config.yaml`）和出站（`agw-egress-config.yaml`）Agent Gateway；3) 通过 `gcloud beta service-extensions authz-extensions import` 导入 Authz Extension（`agw-authz-extension.yaml`）；4) 通过 `gcloud beta network-security authz-policies import` 导入 Authz Policy（`agw-authz-policy.yaml`）。
13. 安全验证：1) 入站 403 未认证测试：提供 scripts/validate_ingress_unauth.sh 中可复制粘贴的 curl 命令，向 Reasoning Engine 端点发送未认证 POST 请求，预期 HTTP 403 Forbidden；2) 出站验证必须用 Python 脚本（scripts/verify_egress_policies.py），通过出站网关发送 JSON-RPC `tools/call` 请求（`get_account_balance`），验证允许的工具返回 HTTP 200；3) 生成 `model-armor-payload.json`，包含提示注入/越狱指令。
14. 故障排查——入站 403（Client-to-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 命令。
15. 故障排查——出站 403（Agent-to-Anywhere）：根因是 Agent Identity 缺少 `roles/iap.egressor` IAM 绑定、principal ID 格式错误或工具元数据上的 CEL 条件不匹配；修复命令使用 scripts/fix_egress_iap.sh 中的精确 gcloud 命令。
16. 混合 VPN 连接与出站路由：参考 assets/main.tf 中的 Terraform 基线配置（VPC、子网 `private_ip_google_access = true`、PSC 网络附件、`aws.internal.` 的 Cloud DNS 私有转发、HA VPN 网关/路由器）；生成 `agw-egress-config.yaml` 声明 `governedAccessPath: AGENT_TO_ANYWHERE`、指向 PSC 网络附件并在 `dnsPeeringConfig` 中引用 `aws.internal.`；参考 scripts/hybrid_vpn_agent.py 初始化 Vertex AI（带 `agent_to_anywhere_config` 引用出站网关）、启用遥测并使用 `types.IdentityType.AGENT_IDENTITY` 部署 `HybridAgent`。
17. 私有出站 GKE 内部负载均衡器：通过内部负载均衡器（ILB）在字面 IP `10.0.1.50` 暴露 GKE 内部 MCP 工具服务器，经 Agent Gateway PSC Interface + Cloud DNS 私有区域连接；使用 scripts/create_gke_dns_record.sh 中的命令将私有域名映射到 GKE 私有 ILB IP `10.0.1.50`；注意 Agent Gateway 出站不原生信任自签名证书或私有企业 CA，必须使用受信任 CA（如 Let's Encrypt）签名的公信 TLS 证书。
18. 治理控制 Model Armor + SGP：1) 生成 `model-armor-config.yaml` 含 `piAndJailbreakFilterSettings` 和 `sdpFilterSettings`（`filterEnforcement: ENFORCE`）；2) 生成 `sgp-policy.yaml` 含自然语言约束，阻止超过 $1000 的交易并脱敏 PII；3) 提供 scripts/enforce_sgp_patch.sh 中的 curl PATCH 命令，将 `authzExtensions` 的 `sgpEnforcementMode` 设为 `ENFORCE`。
19. 多智能体 Cloud Run 出站路由：不要生成计划工件或停在规划阶段，直接生成所有组件：1) 生成 `agw-egress-config-run.yaml` 声明 `governedAccessPath: AGENT_TO_ANYWHERE`、PSC 网络附件和 `*.run.app` 的 DNS 对等；2) 使用 scripts/register_cloud_run_services.sh 中的命令在 `us-east4` Agent Registry 注册全部 3 个 Cloud Run 服务（`marketing-tool-service`、`sales-tool-service`、`support-tool-service`）；3) 生成 `iap-policy.json` 在 `roles/iap.egressor` 下的 `members` 列表中包含全部 3 个 `principal://` 绑定；4) 参考 scripts/multi_agent_cloud_run.py 中的完整 GenAI SDK 部署脚本。
20. 高级 Model Armor 过滤：自定义关键词匹配时配置 `userDefinedFilterSettings`（见 assets/model-armor-advanced.yaml）。
21. 已知陷阱：`network_attachment` 是 `ForceNew`，初始 Terraform apply 后启用 SGP 或修改网络附件会强制重建网关资源，若管理不当可能在销毁时造成依赖死锁，需规划基础设施顺序；Agent Gateway 最多允许同时附加 4 个自定义授权策略，确保安全策略在此限制内合并规则。

适用边界 · 注意事项

• 不适用于与 Agent Gateway 无关的通用 Cloud Load Balancing 或基础 VPC 设置。
• 设计阶段不要对真实云资源执行部署或验证命令（gcloud、kubectl、terraform、curl）。
• 出站策略验证不要使用 curl，必须使用 Python 脚本。