google-cloud-solution-multi-agent-security
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAgent Gateway multi-agent security
Agent Gateway多代理安全
Critical Enforcement Rules & Rationale
关键执行规则与原理
- Gcloud Release Tracks: Always use the exact release tracks specified in
the commands (e.g., ). Omitting these prefixes causes commands to fail because Agent Gateway features are located in specialized, non-default namespaces.
gcloud beta network-services agent-gateways - API Enablement: Include in the API enablement list when setting up guardrails. Excluding it prevents Model Armor policies and filters from successfully attaching to the Gateway.
modelarmor.googleapis.com - Egress Verification: Egress policy verification requires using the
Python script
(scripts/verify_egress_policies.py),
not . Egress gateways rely on runtime SDK lifecycle handling and JWT context that a standard curl command cannot simulate correctly.
curl - Model Armor Keys: In , always include both
model-armor-config.yamlandpiAndJailbreakFilterSettings(sdpFilterSettings). Invalid or missing filters cause deployment validation failures or lead to silent bypasses of the guardrails.filterEnforcement: ENFORCE - Subnet Private Access: Any subnet hosting a Private Service Connect
network attachment for Egress Gateways must have enabled in Terraform. Disabling this blocks connectivity to Google-managed endpoints, causing total routing failures for agents.
private_ip_google_access = true - Direct Delivery: Immediately provide the requested architecture, configuration files, CLI commands, scripts, and diagrams in full. Do not stop at a planning phase, do not generate a plan artifact, and do not ask for user confirmation before delivering outputs.
- No Infrastructure Execution: Do not attempt to run deployment or
verification commands (such as ,
gcloud,kubectl, orterraform) against real cloud resources during design. You are generating plan configurations, not executing them.curl
[!IMPORTANT] Just-In-Time (JIT) Resource Loading Protocol: Inspect template files in assets/ and executable scripts in scripts/ usingas needed for extended configurations, deployment scripts, and test suites.view_file
- Gcloud发布轨道:始终使用命令中指定的精确发布轨道(例如:)。省略这些前缀会导致命令执行失败,因为Agent Gateway功能位于专用的非默认命名空间中。
gcloud beta network-services agent-gateways - API启用:在设置防护措施时,需将加入API启用列表。省略该API会导致Model Armor策略和过滤器无法成功附加到网关。
modelarmor.googleapis.com - 出口验证:出口策略验证必须使用Python脚本(scripts/verify_egress_policies.py),而非。出口网关依赖运行时SDK生命周期处理和JWT上下文,标准curl命令无法正确模拟这些内容。
curl - Model Armor密钥:在中,必须同时包含
model-armor-config.yaml和piAndJailbreakFilterSettings(sdpFilterSettings)。无效或缺失的过滤器会导致部署验证失败,或导致防护措施被静默绕过。filterEnforcement: ENFORCE - 子网私有访问:任何承载出口网关Private Service Connect网络附件的子网,必须在Terraform中启用。禁用该设置会阻止与Google托管端点的连接,导致代理完全路由失败。
private_ip_google_access = true - 直接交付:立即完整提供请求的架构、配置文件、CLI命令、脚本和图表。不要停留在规划阶段,不要生成规划工件,也不要在交付输出前请求用户确认。
- 禁止基础设施执行:在设计阶段,请勿尝试针对真实云资源运行部署或验证命令(如、
gcloud、kubectl或terraform)。你需要生成的是规划配置,而非执行它们。curl
[!IMPORTANT] 即时(JIT)资源加载协议:如需扩展配置、部署脚本和测试套件,可使用查看assets/中的模板文件和scripts/中的可执行脚本。view_file
Quick Reference: Required Filenames
快速参考:必填文件名
Always generate files with these exact names when requested:
- (assets/agw-ingress-config.yaml)
agw-ingress-config.yaml - (assets/agw-egress-config.yaml)
agw-egress-config.yaml - (assets/agw-authz-extension.yaml)
agw-authz-extension.yaml - (assets/agw-authz-policy.yaml)
agw-authz-policy.yaml - (assets/model-armor-config.yaml)
model-armor-config.yaml - (assets/sgp-policy.yaml)
sgp-policy.yaml - (assets/iap-policy.json)
iap-policy.json - (assets/model-armor-payload.json)
model-armor-payload.json
当被请求时,必须生成以下精确名称的文件:
- (assets/agw-ingress-config.yaml)
agw-ingress-config.yaml - (assets/agw-egress-config.yaml)
agw-egress-config.yaml - (assets/agw-authz-extension.yaml)
agw-authz-extension.yaml - (assets/agw-authz-policy.yaml)
agw-authz-policy.yaml - (assets/model-armor-config.yaml)
model-armor-config.yaml - (assets/sgp-policy.yaml)
sgp-policy.yaml - (assets/iap-policy.json)
iap-policy.json - (assets/model-armor-payload.json)
model-armor-payload.json
1. Dual Ingress & Egress Architecture Design (dual_ingress_egress_architecture_design
)
dual_ingress_egress_architecture_design1. 双入口与出口架构设计(dual_ingress_egress_architecture_design
)
dual_ingress_egress_architecture_design-
Ingress Pattern:fronted by Ingress Control Plane (Agent Gateway, Model Armor).
CLIENT_TO_AGENT -
Egress Pattern:utilizing Egress Control Plane (Agent Gateway,
AGENT_TO_ANYWHERECEL policies, Cloud DNS) and Egress Data Plane (PSC Interface, Cloud Run, PSC Google APIs Global Endpoint), coordinated via Agent Registry & Agent Engine runtime.roles/iap.egressor -
Mermaid Diagram: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"]
-
入口模式:由入口控制平面(Agent Gateway、Model Armor)提供支持的。
CLIENT_TO_AGENT -
出口模式:利用出口控制平面(Agent Gateway、CEL策略、Cloud DNS)和出口数据平面(PSC接口、Cloud Run、PSC Google APIs全局端点)的
roles/iap.egressor,通过Agent Registry和Agent Engine运行时进行协调。AGENT_TO_ANYWHERE -
Mermaid图表: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 & Egress Guardrail Policy Config (ingress_and_egress_guardrail_policy_config
)
ingress_and_egress_guardrail_policy_config2. 入口与出口防护策略配置(ingress_and_egress_guardrail_policy_config
)
ingress_and_egress_guardrail_policy_configWhen requested for Ingress & Egress guardrail policy configs, you MUST generate
and create all required files in the workspace:
- (assets/agw-ingress-config.yaml): Declares
agw-ingress-config.yamlwith protocolsgovernedAccessPath: CLIENT_TO_AGENTandHTTP.MCP - (assets/agw-egress-config.yaml): Declares
agw-egress-config.yamlwith protocolgovernedAccessPath: AGENT_TO_ANYWHERE.MCP - (assets/agw-authz-extension.yaml): Configures AuthzExtension service for IAP authorization.
agw-authz-extension.yaml - (assets/agw-authz-policy.yaml): Configures
agw-authz-policy.yamlactionAuthzPolicytargeting both Ingress and Egress gateways.ALLOW - (assets/iap-policy.json): Binds
iap-policy.jsonwith CEL condition checkingroles/iap.egressor.iap.googleapis.com/mcp.toolName == 'get_account_balance' && iap.googleapis.com/mcp.tool.isReadOnly == true - (assets/model-armor-config.yaml): Enables
model-armor-config.yamlandpiAndJailbreakFilterSettingswithsdpFilterSettings.filterEnforcement: ENFORCE - (assets/sgp-policy.yaml): Implements Natural Language Constraints blocking transactions > $1000 and sanitizing PII.
sgp-policy.yaml
当被请求提供入口与出口防护策略配置时,必须在工作区中生成并创建所有必填文件:
- (assets/agw-ingress-config.yaml):声明
agw-ingress-config.yaml,支持governedAccessPath: CLIENT_TO_AGENT和HTTP协议。MCP - (assets/agw-egress-config.yaml):声明
agw-egress-config.yaml,支持governedAccessPath: AGENT_TO_ANYWHERE协议。MCP - (assets/agw-authz-extension.yaml):配置AuthzExtension服务以实现IAP授权。
agw-authz-extension.yaml - (assets/agw-authz-policy.yaml):配置针对入口和出口网关的
agw-authz-policy.yaml允许动作。AuthzPolicy - (assets/iap-policy.json):绑定
iap-policy.json,并添加CEL条件检查roles/iap.egressor。iap.googleapis.com/mcp.toolName == 'get_account_balance' && iap.googleapis.com/mcp.tool.isReadOnly == true - (assets/model-armor-config.yaml):启用
model-armor-config.yaml和piAndJailbreakFilterSettings,并设置sdpFilterSettings。filterEnforcement: ENFORCE - (assets/sgp-policy.yaml):实现自然语言约束,阻止超过1000美元的交易并清理PII数据。
sgp-policy.yaml
3. Ingress & Egress Infrastructure Deployment (ingress_and_egress_infrastructure_deployment
)
ingress_and_egress_infrastructure_deployment3. 入口与出口基础设施部署(ingress_and_egress_infrastructure_deployment
)
ingress_and_egress_infrastructure_deploymentInspect and provide the step-by-step CLI commands from
scripts/deploy_infrastructure.sh:
gcloud- Enable Required APIs: ,
compute,networkservices,networksecurity,modelarmor,iap,agentregistry, andserviceextensions.aiplatform - Import Agent Gateways: Ingress () and Egress (
agw-ingress-config.yaml) viaagw-egress-config.yaml.gcloud alpha network-services agent-gateways import - Import Authz Extension: via
agw-authz-extension.yaml.gcloud beta service-extensions authz-extensions import - Import Authz Policy: via
agw-authz-policy.yaml.gcloud beta network-security authz-policies import
查看并提供scripts/deploy_infrastructure.sh中的分步 CLI命令:
gcloud- 启用必填API:、
compute、networkservices、networksecurity、modelarmor、iap、agentregistry和serviceextensions。aiplatform - 导入Agent网关:通过导入入口(
gcloud alpha network-services agent-gateways import)和出口(agw-ingress-config.yaml)网关。agw-egress-config.yaml - 导入授权扩展:通过导入
gcloud beta service-extensions authz-extensions import。agw-authz-extension.yaml - 导入授权策略:通过导入
gcloud beta network-security authz-policies import。agw-authz-policy.yaml
4. Ingress & Egress Security Validation (ingress_and_egress_security_validation
)
ingress_and_egress_security_validation4. 入口与出口安全验证(ingress_and_egress_security_validation
)
ingress_and_egress_security_validationWhen validating security for Ingress and Egress:
- Ingress 403 Unauthenticated Test: Provide the copy-pasteable verification curl command from scripts/validate_ingress_unauth.sh sending an unauthenticated POST request to the Reasoning Engine endpoint expecting HTTP 403 Forbidden.
- Python Egress Verification Script (MUST use Python script snippet, NOT
curl): Provide the Python verification script snippet from
scripts/verify_egress_policies.py
sending JSON-RPC requests (
tools/call) through the Egress Gateway to verify HTTP 200 for allowed tools.get_account_balance - Model Armor Test Payload: Generate (assets/model-armor-payload.json) containing prompt injection/jailbreak instructions.
model-armor-payload.json
验证入口和出口安全性时:
- 入口未认证403测试:提供scripts/validate_ingress_unauth.sh中的可复制验证curl命令,向推理引擎端点发送未认证POST请求,预期返回HTTP 403 Forbidden。
- Python出口验证脚本(必须使用Python代码片段,而非curl):提供scripts/verify_egress_policies.py中的Python验证代码片段,通过出口网关发送JSON-RPC 请求(
tools/call),验证允许的工具返回HTTP 200。get_account_balance - Model Armor测试负载:生成包含提示注入/越狱指令的(assets/model-armor-payload.json)。
model-armor-payload.json
5. Troubleshooting Ingress & Egress Failures (troubleshooting_ingress_and_egress_failures
)
troubleshooting_ingress_and_egress_failures5. 入口与出口故障排查(troubleshooting_ingress_and_egress_failures
)
troubleshooting_ingress_and_egress_failures-
Ingress 403 (Client-to-Agent):
- Root Cause: Unauthenticated client requests or missing/invalid OAuth 2.0 / IAP identity tokens.
- OAuth Configuration Steps:
- Configure OAuth 2.0 Client ID credentials in Google Cloud Console.
- Grant the client identity / service account
permission.
roles/iap.httpsResourceAccessor - Exchange credentials with Google OAuth to acquire an OIDC / OAuth ID token.
- Pass the token in the header.
Authorization: Bearer <TOKEN>
- Verification Command: Provide the curl command from scripts/verify_ingress_auth.sh.
-
Egress 403 (Agent-to-Anywhere):
- Root Cause: Missing IAM bindings on the Agent Identity, malformed principal ID, or mismatched CEL condition on tool metadata.
roles/iap.egressor - Fix Command: Provide the exact command from scripts/fix_egress_iap.sh.
gcloud
- Root Cause: Missing
-
入口403错误(客户端到代理):
- 根本原因:未认证的客户端请求,或缺失/无效的OAuth 2.0 / IAP身份令牌。
- OAuth配置步骤:
- 在Google Cloud控制台中配置OAuth 2.0客户端ID凭据。
- 为客户端身份/服务账号授予权限。
roles/iap.httpsResourceAccessor - 与Google OAuth交换凭据以获取OIDC / OAuth ID令牌。
- 在请求头中传递该令牌。
Authorization: Bearer <TOKEN>
- 验证命令:提供scripts/verify_ingress_auth.sh中的curl命令。
-
出口403错误(代理到任意地址):
- 根本原因:代理身份缺失IAM绑定、主体ID格式错误,或工具元数据的CEL条件不匹配。
roles/iap.egressor - 修复命令:提供scripts/fix_egress_iap.sh中的精确命令。
gcloud
- 根本原因:代理身份缺失
6. Hybrid VPN Connectivity & Egress Routing (hybrid_vpn_connectivity_egress_routing
)
hybrid_vpn_connectivity_egress_routing6. 混合VPN连接与出口路由(hybrid_vpn_connectivity_egress_routing
)
hybrid_vpn_connectivity_egress_routing- Terraform HCL: Refer to baseline Terraform config in
assets/main.tf for VPC, subnets
(), PSC network attachment, Cloud DNS private forwarding for
private_ip_google_access = true, and HA VPN gateway/router.aws.internal. - Egress Gateway Config (): Generate configuration declaring
agw-egress-config.yaml, pointing to the PSC network attachment, and referencinggovernedAccessPath: AGENT_TO_ANYWHEREinaws.internal.(see assets/agw-egress-config.yaml).dnsPeeringConfig - Python SDK Deployment Script: Refer to
scripts/hybrid_vpn_agent.py for the complete
script initializing Vertex AI with referencing the Egress Gateway, enabling telemetry, and deploying
agent_to_anywhere_configusingHybridAgent.types.IdentityType.AGENT_IDENTITY
- Terraform HCL:参考assets/main.tf中的基线Terraform配置,包含VPC、子网()、PSC网络附件、针对
private_ip_google_access = true的Cloud DNS私有转发,以及HA VPN网关/路由器。aws.internal. - 出口网关配置():生成声明
agw-egress-config.yaml的配置,指向PSC网络附件,并在governedAccessPath: AGENT_TO_ANYWHERE中引用dnsPeeringConfig(见assets/agw-egress-config.yaml)。aws.internal. - Python SDK部署脚本:参考scripts/hybrid_vpn_agent.py中的完整脚本,该脚本初始化Vertex AI,使用引用出口网关的,启用遥测,并使用
agent_to_anywhere_config部署types.IdentityType.AGENT_IDENTITY。HybridAgent
7. Private Egress GKE Internal Load Balancer (private_egress_gke_internal_load_balancer
)
private_egress_gke_internal_load_balancer7. 私有出口GKE内部负载均衡器(private_egress_gke_internal_load_balancer
)
private_egress_gke_internal_load_balancer- Expose GKE internal MCP tool server via an Internal Load Balancer (ILB) at
literal IP , connecting via Agent Gateway PSC Interface + Cloud DNS Private zone.
10.0.1.50 - Cloud DNS Record Mapping: Provide the command from
scripts/create_gke_dns_record.sh mapping
the private domain to GKE's private ILB IP .
10.0.1.50 - Explicit TLS Warning: Agent Gateway egress does not natively trust self-signed certificates or private enterprise CAs. You must use publicly trusted TLS certificates signed by a trusted Certificate Authority (e.g., Let's Encrypt).
- 通过内部负载均衡器(ILB)暴露GKE内部MCP工具服务器,固定IP为,通过Agent Gateway PSC接口+Cloud DNS私有区域连接。
10.0.1.50 - Cloud DNS记录映射:提供scripts/create_gke_dns_record.sh中的命令,将私有域映射到GKE的私有ILB IP 。
10.0.1.50 - 明确TLS警告:Agent Gateway出口不原生信任自签名证书或私有企业CA。你必须使用受信任证书颁发机构(如Let's Encrypt)签名的公开可信TLS证书。
8. Governance Controls Model Armor SGP (governance_controls_model_armor_sgp
)
governance_controls_model_armor_sgp8. 治理控制Model Armor SGP(governance_controls_model_armor_sgp
)
governance_controls_model_armor_sgpWhen configuring dual safety layers with Model Armor on Ingress and SGP on
Egress:
- Model Armor Config: Generate (assets/model-armor-config.yaml) with
model-armor-config.yamlandpiAndJailbreakFilterSettings(sdpFilterSettings).filterEnforcement: ENFORCE - Semantic Governance Policy: Generate (assets/sgp-policy.yaml) with Natural Language Constraints blocking transactions > $1000 and sanitizing PII.
sgp-policy.yaml - Curl PATCH Command: Provide the curl command from
scripts/enforce_sgp_patch.sh to update
with
authzExtensionsset tosgpEnforcementMode.ENFORCE
在入口配置Model Armor、在出口配置SGP的双重安全层时:
- Model Armor配置:生成包含和
piAndJailbreakFilterSettings(sdpFilterSettings)的filterEnforcement: ENFORCE(assets/model-armor-config.yaml)。model-armor-config.yaml - 语义治理策略:生成包含自然语言约束(阻止超过1000美元的交易并清理PII数据)的(assets/sgp-policy.yaml)。
sgp-policy.yaml - curl PATCH命令:提供scripts/enforce_sgp_patch.sh中的curl命令,将更新为
authzExtensions。sgpEnforcementMode: ENFORCE
9. Multi-Agent Cloud Run Egress Routing (multi_agent_cloud_run_egress_routing
)
multi_agent_cloud_run_egress_routing9. 多代理Cloud Run出口路由(multi_agent_cloud_run_egress_routing
)
multi_agent_cloud_run_egress_routingDo NOT produce a plan artifact or stop at planning. When configuring multi-agent
Cloud Run egress routing, you MUST directly provide and generate ALL required
components:
- Egress Gateway Config (): Generate configuration declaring
agw-egress-config-run.yaml, PSC network attachment, and DNS peering forgovernedAccessPath: AGENT_TO_ANYWHERE(see assets/agw-egress-config-run.yaml).*.run.app - Register Cloud Run Services in Agent Registry: Provide the registration
commands from
scripts/register_cloud_run_services.sh
registering all 3 Cloud Run services (,
marketing-tool-service,sales-tool-service) in thesupport-tool-serviceAgent Registry.us-east4 - (Multi-Agent): Generate
iap-policy.json(assets/iap-policy-multi-agent.json) containing all 3iap-policy.jsonbindings in theprincipal://list undermembers.roles/iap.egressor - Python SDK Deployment Script: Refer to scripts/multi_agent_cloud_run.py for the complete GenAI SDK deployment script.
请勿生成规划工件或停留在规划阶段。配置多代理Cloud Run出口路由时,必须直接提供并生成所有必填组件:
- 出口网关配置():生成声明
agw-egress-config-run.yaml、PSC网络附件,以及针对governedAccessPath: AGENT_TO_ANYWHERE的DNS peering配置(见assets/agw-egress-config-run.yaml)。*.run.app - 在Agent Registry中注册Cloud Run服务:提供scripts/register_cloud_run_services.sh中的注册命令,在区域的Agent Registry中注册所有3个Cloud Run服务(
us-east4、marketing-tool-service、sales-tool-service)。support-tool-service - 多代理:生成包含
iap-policy.json下roles/iap.egressor列表中所有3个members绑定的principal://(assets/iap-policy-multi-agent.json)。iap-policy.json - Python SDK部署脚本:参考scripts/multi_agent_cloud_run.py中的完整GenAI SDK部署脚本。
10. Advanced Model Armor Filtering (advanced_model_armor_filtering
)
advanced_model_armor_filtering10. 高级Model Armor过滤(advanced_model_armor_filtering
)
advanced_model_armor_filteringFor custom keyword matching, configure (see
assets/model-armor-advanced.yaml).
userDefinedFilterSettings如需自定义关键词匹配,可配置(见assets/model-armor-advanced.yaml)。
userDefinedFilterSettings11. Known Traps & Gotchas (known_traps_and_gotchas
)
known_traps_and_gotchas11. 已知陷阱与注意事项(known_traps_and_gotchas
)
known_traps_and_gotchas- is
network_attachment: Enabling Semantic Governance Policies (SGP) or modifying network attachments after the initial Terraform apply will force-recreate the gateway resource. If not managed carefully, this can cause dependency deadlocks during destroy operations. Plan infrastructure sequencing accordingly.ForceNew - Authz Policy Limit: An Agent Gateway allows at most 4 custom authorization policies attached concurrently. Ensure your security posture consolidates rules within this limit.
- 为
network_attachment类型:在初始Terraform应用后启用语义治理策略(SGP)或修改网络附件,会强制重新创建网关资源。如果管理不当,这可能会在销毁操作期间导致依赖死锁。请相应规划基础设施的部署顺序。ForceNew - 授权策略限制:一个Agent Gateway最多允许同时附加4个自定义授权策略。请确保你的安全策略在该限制内整合规则。