google-cloud-solution-multi-agent-security

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent 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.,
    gcloud beta network-services agent-gateways
    ). Omitting these prefixes causes commands to fail because Agent Gateway features are located in specialized, non-default namespaces.
  • API Enablement: Include
    modelarmor.googleapis.com
    in the API enablement list when setting up guardrails. Excluding it prevents Model Armor policies and filters from successfully attaching to the Gateway.
  • Egress Verification: Egress policy verification requires using the Python script (scripts/verify_egress_policies.py), not
    curl
    . Egress gateways rely on runtime SDK lifecycle handling and JWT context that a standard curl command cannot simulate correctly.
  • Model Armor Keys: In
    model-armor-config.yaml
    , always include both
    piAndJailbreakFilterSettings
    and
    sdpFilterSettings
    (
    filterEnforcement: ENFORCE
    ). Invalid or missing filters cause deployment validation failures or lead to silent bypasses of the guardrails.
  • Subnet Private Access: Any subnet hosting a Private Service Connect network attachment for Egress Gateways must have
    private_ip_google_access = true
    enabled in Terraform. Disabling this blocks connectivity to Google-managed endpoints, causing total routing failures for agents.
  • 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
    ,
    terraform
    , or
    curl
    ) against real cloud resources during design. You are generating plan configurations, not executing them.
[!IMPORTANT] Just-In-Time (JIT) Resource Loading Protocol: Inspect template files in assets/ and executable scripts in scripts/ using
view_file
as needed for extended configurations, deployment scripts, and test suites.

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

Quick Reference: Required Filenames

快速参考:必填文件名

Always generate files with these exact names when requested:
  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. 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 (
dual_ingress_egress_architecture_design
)

1. 双入口与出口架构设计(
dual_ingress_egress_architecture_design

  • Ingress Pattern:
    CLIENT_TO_AGENT
    fronted by Ingress Control Plane (Agent Gateway, Model Armor).
  • Egress Pattern:
    AGENT_TO_ANYWHERE
    utilizing Egress Control Plane (Agent Gateway,
    roles/iap.egressor
    CEL policies, Cloud DNS) and Egress Data Plane (PSC Interface, Cloud Run, PSC Google APIs Global Endpoint), coordinated via Agent Registry & Agent Engine runtime.
  • 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、
    roles/iap.egressor
    CEL策略、Cloud DNS)和出口数据平面(PSC接口、Cloud Run、PSC Google APIs全局端点)的
    AGENT_TO_ANYWHERE
    ,通过Agent Registry和Agent Engine运行时进行协调。
  • 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
)

2. 入口与出口防护策略配置(
ingress_and_egress_guardrail_policy_config

When requested for Ingress & Egress guardrail policy configs, you MUST generate and create all required files in the workspace:
  • agw-ingress-config.yaml
    (assets/agw-ingress-config.yaml): Declares
    governedAccessPath: CLIENT_TO_AGENT
    with protocols
    HTTP
    and
    MCP
    .
  • agw-egress-config.yaml
    (assets/agw-egress-config.yaml): Declares
    governedAccessPath: AGENT_TO_ANYWHERE
    with protocol
    MCP
    .
  • agw-authz-extension.yaml
    (assets/agw-authz-extension.yaml): Configures AuthzExtension service for IAP authorization.
  • agw-authz-policy.yaml
    (assets/agw-authz-policy.yaml): Configures
    AuthzPolicy
    action
    ALLOW
    targeting both Ingress and Egress gateways.
  • iap-policy.json
    (assets/iap-policy.json): Binds
    roles/iap.egressor
    with CEL condition checking
    iap.googleapis.com/mcp.toolName == 'get_account_balance' && iap.googleapis.com/mcp.tool.isReadOnly == true
    .
  • model-armor-config.yaml
    (assets/model-armor-config.yaml): Enables
    piAndJailbreakFilterSettings
    and
    sdpFilterSettings
    with
    filterEnforcement: ENFORCE
    .
  • sgp-policy.yaml
    (assets/sgp-policy.yaml): Implements Natural Language Constraints blocking transactions > $1000 and sanitizing PII.

当被请求提供入口与出口防护策略配置时,必须在工作区中生成并创建所有必填文件:
  • 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):配置AuthzExtension服务以实现IAP授权。
  • agw-authz-policy.yaml
    assets/agw-authz-policy.yaml):配置针对入口和出口网关的
    AuthzPolicy
    允许动作。
  • 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 & Egress Infrastructure Deployment (
ingress_and_egress_infrastructure_deployment
)

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

Inspect and provide the step-by-step
gcloud
CLI commands from scripts/deploy_infrastructure.sh:
  1. Enable Required APIs:
    compute
    ,
    networkservices
    ,
    networksecurity
    ,
    modelarmor
    ,
    iap
    ,
    agentregistry
    ,
    serviceextensions
    , and
    aiplatform
    .
  2. Import Agent Gateways: Ingress (
    agw-ingress-config.yaml
    ) and Egress (
    agw-egress-config.yaml
    ) via
    gcloud alpha network-services agent-gateways import
    .
  3. Import Authz Extension:
    agw-authz-extension.yaml
    via
    gcloud beta service-extensions authz-extensions import
    .
  4. Import Authz Policy:
    agw-authz-policy.yaml
    via
    gcloud beta network-security authz-policies import
    .

查看并提供scripts/deploy_infrastructure.sh中的分步
gcloud
CLI命令:
  1. 启用必填API
    compute
    networkservices
    networksecurity
    modelarmor
    iap
    agentregistry
    serviceextensions
    aiplatform
  2. 导入Agent网关:通过
    gcloud alpha network-services agent-gateways import
    导入入口(
    agw-ingress-config.yaml
    )和出口(
    agw-egress-config.yaml
    )网关。
  3. 导入授权扩展:通过
    gcloud beta service-extensions authz-extensions import
    导入
    agw-authz-extension.yaml
  4. 导入授权策略:通过
    gcloud beta network-security authz-policies import
    导入
    agw-authz-policy.yaml

4. Ingress & Egress Security Validation (
ingress_and_egress_security_validation
)

4. 入口与出口安全验证(
ingress_and_egress_security_validation

When validating security for Ingress and Egress:
  1. 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.
  2. 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
    tools/call
    requests (
    get_account_balance
    ) through the Egress Gateway to verify HTTP 200 for allowed tools.
  3. Model Armor Test Payload: Generate
    model-armor-payload.json
    (assets/model-armor-payload.json) containing prompt injection/jailbreak instructions.

验证入口和出口安全性时:
  1. 入口未认证403测试:提供scripts/validate_ingress_unauth.sh中的可复制验证curl命令,向推理引擎端点发送未认证POST请求,预期返回HTTP 403 Forbidden。
  2. Python出口验证脚本(必须使用Python代码片段,而非curl):提供scripts/verify_egress_policies.py中的Python验证代码片段,通过出口网关发送JSON-RPC
    tools/call
    请求(
    get_account_balance
    ),验证允许的工具返回HTTP 200。
  3. Model Armor测试负载:生成包含提示注入/越狱指令的
    model-armor-payload.json
    assets/model-armor-payload.json)。

5. Troubleshooting Ingress & Egress Failures (
troubleshooting_ingress_and_egress_failures
)

5. 入口与出口故障排查(
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:
      1. Configure OAuth 2.0 Client ID credentials in Google Cloud Console.
      2. Grant the client identity / service account
        roles/iap.httpsResourceAccessor
        permission.
      3. Exchange credentials with Google OAuth to acquire an OIDC / OAuth ID token.
      4. Pass the token in the
        Authorization: Bearer <TOKEN>
        header.
    • Verification Command: Provide the curl command from scripts/verify_ingress_auth.sh.
  • Egress 403 (Agent-to-Anywhere):
    • Root Cause: Missing
      roles/iap.egressor
      IAM bindings on the Agent Identity, malformed principal ID, or mismatched CEL condition on tool metadata.
    • Fix Command: Provide the exact
      gcloud
      command from scripts/fix_egress_iap.sh.

  • 入口403错误(客户端到代理)
    • 根本原因:未认证的客户端请求,或缺失/无效的OAuth 2.0 / IAP身份令牌。
    • OAuth配置步骤
      1. 在Google Cloud控制台中配置OAuth 2.0客户端ID凭据。
      2. 为客户端身份/服务账号授予
        roles/iap.httpsResourceAccessor
        权限。
      3. 与Google OAuth交换凭据以获取OIDC / OAuth ID令牌。
      4. Authorization: Bearer <TOKEN>
        请求头中传递该令牌。
    • 验证命令:提供scripts/verify_ingress_auth.sh中的curl命令。
  • 出口403错误(代理到任意地址)
    • 根本原因:代理身份缺失
      roles/iap.egressor
      IAM绑定、主体ID格式错误,或工具元数据的CEL条件不匹配。
    • 修复命令:提供scripts/fix_egress_iap.sh中的精确
      gcloud
      命令。

6. Hybrid VPN Connectivity & Egress Routing (
hybrid_vpn_connectivity_egress_routing
)

6. 混合VPN连接与出口路由(
hybrid_vpn_connectivity_egress_routing

  • Terraform HCL: Refer to baseline Terraform config in assets/main.tf for VPC, subnets (
    private_ip_google_access = true
    ), PSC network attachment, Cloud DNS private forwarding for
    aws.internal.
    , and HA VPN gateway/router.
  • Egress Gateway Config (
    agw-egress-config.yaml
    )
    : Generate configuration declaring
    governedAccessPath: AGENT_TO_ANYWHERE
    , pointing to the PSC network attachment, and referencing
    aws.internal.
    in
    dnsPeeringConfig
    (see assets/agw-egress-config.yaml).
  • Python SDK Deployment Script: Refer to scripts/hybrid_vpn_agent.py for the complete script initializing Vertex AI with
    agent_to_anywhere_config
    referencing the Egress Gateway, enabling telemetry, and deploying
    HybridAgent
    using
    types.IdentityType.AGENT_IDENTITY
    .

  • Terraform HCL:参考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.
    (见assets/agw-egress-config.yaml)。
  • 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
)

7. 私有出口GKE内部负载均衡器(
private_egress_gke_internal_load_balancer

  • Expose GKE internal MCP tool server via an Internal Load Balancer (ILB) at literal IP
    10.0.1.50
    , connecting via Agent Gateway PSC Interface + Cloud DNS Private zone.
  • 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为
    10.0.1.50
    ,通过Agent Gateway PSC接口+Cloud DNS私有区域连接。
  • 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
)

8. 治理控制Model Armor SGP(
governance_controls_model_armor_sgp

When configuring dual safety layers with Model Armor on Ingress and SGP on Egress:
  1. Model Armor Config: Generate
    model-armor-config.yaml
    (assets/model-armor-config.yaml) with
    piAndJailbreakFilterSettings
    and
    sdpFilterSettings
    (
    filterEnforcement: ENFORCE
    ).
  2. Semantic Governance Policy: Generate
    sgp-policy.yaml
    (assets/sgp-policy.yaml) with Natural Language Constraints blocking transactions > $1000 and sanitizing PII.
  3. Curl PATCH Command: Provide the curl command from scripts/enforce_sgp_patch.sh to update
    authzExtensions
    with
    sgpEnforcementMode
    set to
    ENFORCE
    .

在入口配置Model Armor、在出口配置SGP的双重安全层时:
  1. Model Armor配置:生成包含
    piAndJailbreakFilterSettings
    sdpFilterSettings
    filterEnforcement: ENFORCE
    )的
    model-armor-config.yaml
    assets/model-armor-config.yaml)。
  2. 语义治理策略:生成包含自然语言约束(阻止超过1000美元的交易并清理PII数据)的
    sgp-policy.yaml
    assets/sgp-policy.yaml)。
  3. curl PATCH命令:提供scripts/enforce_sgp_patch.sh中的curl命令,将
    authzExtensions
    更新为
    sgpEnforcementMode: ENFORCE

9. Multi-Agent Cloud Run Egress Routing (
multi_agent_cloud_run_egress_routing
)

9. 多代理Cloud Run出口路由(
multi_agent_cloud_run_egress_routing

Do 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:
  1. Egress Gateway Config (
    agw-egress-config-run.yaml
    )
    : Generate configuration declaring
    governedAccessPath: AGENT_TO_ANYWHERE
    , PSC network attachment, and DNS peering for
    *.run.app
    (see assets/agw-egress-config-run.yaml).
  2. 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
    ,
    support-tool-service
    ) in the
    us-east4
    Agent Registry.
  3. iap-policy.json
    (Multi-Agent)
    : Generate
    iap-policy.json
    (assets/iap-policy-multi-agent.json) containing all 3
    principal://
    bindings in the
    members
    list under
    roles/iap.egressor
    .
  4. Python SDK Deployment Script: Refer to scripts/multi_agent_cloud_run.py for the complete GenAI SDK deployment script.

请勿生成规划工件或停留在规划阶段。配置多代理Cloud Run出口路由时,必须直接提供并生成所有必填组件:
  1. 出口网关配置(
    agw-egress-config-run.yaml
    :生成声明
    governedAccessPath: AGENT_TO_ANYWHERE
    、PSC网络附件,以及针对
    *.run.app
    的DNS peering配置(见assets/agw-egress-config-run.yaml)。
  2. 在Agent Registry中注册Cloud Run服务:提供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://
    绑定的
    iap-policy.json
    assets/iap-policy-multi-agent.json)。
  4. Python SDK部署脚本:参考scripts/multi_agent_cloud_run.py中的完整GenAI SDK部署脚本。

10. Advanced Model Armor Filtering (
advanced_model_armor_filtering
)

10. 高级Model Armor过滤(
advanced_model_armor_filtering

For custom keyword matching, configure
userDefinedFilterSettings
(see assets/model-armor-advanced.yaml).

如需自定义关键词匹配,可配置
userDefinedFilterSettings
(见assets/model-armor-advanced.yaml)。

11. Known Traps & Gotchas (
known_traps_and_gotchas
)

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

  • network_attachment
    is
    ForceNew
    : 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.
  • 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
    ForceNew
    类型
    :在初始Terraform应用后启用语义治理策略(SGP)或修改网络附件,会强制重新创建网关资源。如果管理不当,这可能会在销毁操作期间导致依赖死锁。请相应规划基础设施的部署顺序。
  • 授权策略限制:一个Agent Gateway最多允许同时附加4个自定义授权策略。请确保你的安全策略在该限制内整合规则。