排查 Agent Gateway 问题

如果 Cloud Run 智能体的出站请求失败或绕过 Agent Gateway，请使用以下检查来跟踪请求路径，或参阅常见问题和解决方法。如需查看设置说明，请参阅使用 Agent Gateway 治理智能体。

在流量到达 Agent Gateway 之前，Cloud Run Envoy Sidecar 会从 Traffic Director API 提取路由和证书配置。边车通过 mTLS CONNECT 隧道将出站流量发送到 Secure Web Proxy。

在 Envoy Sidecar 访问日志中验证出站路由

当 Cloud Run Envoy 边车拦截出站 TCP 连接时，它会使用 jsonPayload.upstream_host 字段将 JSON 访问日志条目写入 run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log。

从 Cloud Run 服务触发一个出站请求，并查询边车访问日志：

gcloud logging read \
    'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND jsonPayload.upstream_host:*' \
    --project=PROJECT_ID \
    --freshness=7d \
    --limit=20 \
    --format="table(timestamp, jsonPayload.sni, jsonPayload.upstream_host, jsonPayload.response_flags, jsonPayload.bytes_sent, jsonPayload.bytes_received, jsonPayload.duration)"

替换以下内容：

  • SERVICE_NAME：Cloud Run 代理服务的名称。
  • PROJECT_ID：您的 Google Cloud 项目 ID。

通过网关建立的健康连接会返回类似于以下内容的输出：

TIMESTAMP                     SNI          UPSTREAM_HOST                      RESPONSE_FLAGS  BYTES_SENT  BYTES_RECEIVED  DURATION
2026-10-09T05:07:48.340693Z   example.com  envoy://tunnel_internal_listener/  -               4101        2899            489

检查 UPSTREAM_HOST 和 RESPONSE_FLAGS 值：

  • 如果 UPSTREAM_HOST 为 envoy://tunnel_internal_listener/ 且 RESPONSE_FLAGS 为 -，则连接运行状况良好。Envoy sidecar 与您的 EgressRouting 政策匹配，并将连接转发到 Agent Gateway。
  • 如果 UPSTREAM_HOST 是目标 IP 地址和端口（例如 93.184.216.34:443），则 Traffic Director API 无法匹配您的 EgressRouting 政策或解析目标网关。Envoy 使用了 ORIGINAL_DST 直通，并绕过了 Agent Gateway。请参阅审核 EgressRouting 和 AgentGateway 资源 URI。
  • 如果 UPSTREAM_HOST 为 envoy://tunnel_internal_listener/ 且 RESPONSE_FLAGS 为 UF 或 UH，或者 BYTES_RECEIVED 为 0，则 Envoy 无法打开通往 Secure Web Proxy 的 CONNECT 隧道。检查您的虚拟私有云 (VPC) 子网连接，或参阅更新 Secure Web Proxy 网关会破坏 Envoy 隧道。
  • 如果未显示任何行，请检查 run.googleapis.com%2Frequests，确认请求已到达 Cloud Run 容器。验证您的活跃修订版本是否启用了 --ambient-networking。如果行仍未显示，请参阅检查 Envoy 边车 xDS 和连接日志。

检查 Envoy 边车 xDS 和连接日志

如果 Envoy sidecar 访问日志未返回任何条目或显示连接失败，请检查 sidecar xDS 和上游连接日志：

  1. 检查 Traffic Director API xDS 流错误或启动状态：

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (severity>=INFO OR textPayload:"DeltaAggregatedResources")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

  2. 检查上游隧道连接尝试：ambient-swp-connect-cluster

    gcloud logging read \
   'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (textPayload:"ambient-swp-connect-cluster" OR jsonPayload.message:"ambient-swp-connect-cluster" OR jsonPayload.message:"tunnel_internal_listener")' \
   --project=PROJECT_ID \
   --freshness=7d \
   --limit=30 \
   --format="table(timestamp, severity, textPayload, jsonPayload.message)"

    替换以下内容：

    • SERVICE_NAME：Cloud Run 代理服务的名称。
    • PROJECT_ID：您的 Google Cloud 项目 ID。

查看日志消息：

  • 如果日志包含 DeltaAggregatedResources gRPC config stream 和 The caller does not have permission，则服务身份缺少 roles/trafficdirector.client。请参阅 Envoy Sidecar 无法接收 xDS 配置。
  • 如果日志包含 Creating connection to cluster ambient-swp-connect-cluster，则表示 Envoy 收到了 EgressRouting 配置并尝试连接到 Secure Web Proxy。

审核 EgressRouting 和 AgentGateway 资源 URI

当您运行 gcloud alpha network-services egress-routings create 或 gcloud beta network-services agent-gateways import 时，API 会验证 URI 语法，而不会检查目标资源是否存在。资源名称或区域中的拼写错误会导致 Traffic Director API 跳过 EgressRouting 转换，并且 Envoy 会使用直通路由。

检查存储的 URI，并将其与已部署的资源进行比较：

  1. 检查 EgressRouting 资源。输出会将项目 ID 规范化为项目编号：

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
   --location=REGION \
   --project=PROJECT_ID

  2. 列出该区域中的所有 EgressRouting 资源，以确认没有重复的政策定位到同一服务：

    gcloud alpha network-services egress-routings list \
   --location=REGION \
   --project=PROJECT_ID

  3. 验证目标 Secure Web Proxy 网关是否与 EgressRouting.gateway 和 AgentGateway.selfManaged.resourceUris 中的 URI 匹配：

    gcloud network-services gateways describe SWP_NAME \
   --location=REGION \
   --project=PROJECT_ID

    替换以下内容：

    • EGRESS_ROUTING_NAME：您的 EgressRouting 资源的名称。
    • REGION：部署所在的区域。
    • PROJECT_ID：您的 Google Cloud 项目 ID。
    • SWP_NAME：Secure Web Proxy 网关的名称。

验证这三个 URI 是否都与您的项目 ID 或编号、区域和资源名称匹配：

  • EgressRouting.sources[].workloadUri：
    • 服务级： //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • 项目级：//run.googleapis.com/projects/PROJECT_ID 或 //run.googleapis.com/projects/PROJECT_NUMBER
  • EgressRouting.gateway：//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
  • AgentGateway.selfManaged.resourceUris[]：projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME

查看 Secure Web Proxy 事务日志

如果 Envoy 边车将流量转发到 Secure Web Proxy，但请求失败，请按照查看代理事务日志中的说明检查代理日志：

  • 如果代理日志中未显示任何流量，则表示请求未到达 Secure Web Proxy。在审核 EgressRouting 和 AgentGateway 资源 URI 以及常见问题和解决方法中检查您的 EgressRouting 配置。
  • 如果您看到意外的 DENY 或 ALLOW 决策，请检查日志条目中的 jsonPayload.authzPolicyInfo 和 jsonPayload.agentGatewayInfo，以检查匹配的 AuthzPolicy 和目标元数据，并验证附加到 Agent Gateway 资源的任何 ExtensionBinding 规则。创建或更新 ExtensionBinding 资源后，配置更改最多可能需要 5 分钟才能传播到网关。

常见问题和解决方法

以下部分介绍了常见问题以及解决方法。

由于资源 URI 不匹配，出站流量绕过了 Agent Gateway

来自 Cloud Run 的出站流量会绕过 Agent Gateway，或在 egress-routings create 成功后超时。在 envoy_sidecar_log 中，jsonPayload.upstream_host 显示目标 IP 地址和端口，而不是 envoy://tunnel_internal_listener/。

EgressRouting 或 AgentGateway 资源 URI 之一引用了不存在的资源名称或不匹配的区域。当 Traffic Director API 无法解析从 Cloud Run 服务到 Secure Web Proxy 的链时，它会跳过隧道转换并提供 ORIGINAL_DST。

运行审核 EgressRouting 和 AgentGateway 资源 URI 中的命令，找到不匹配的 URI。使用匹配的资源名称和区域更新配置，然后重新创建 AgentGateway 或 EgressRouting 资源。

Envoy sidecar 无法接收 xDS 配置

来自 Cloud Run 容器的出站请求超时或失败，并且 envoy_sidecar_log 包含以下错误：

DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission

Cloud Run 运行时服务身份没有 roles/trafficdirector.client。默认情况下，使用 --functional-type=agent 和 --identity-type=agent-identity 部署服务会授予 roles/run.agentDefaultAccess，其中包括 roles/trafficdirector.client 和 roles/cloudtrace.agent。如果您的服务身份缺少这些权限，请授予以下角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/cloudtrace.agent"

替换以下内容：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • ORGANIZATION_ID：您的 Google Cloud 组织 ID。
  • PROJECT_NUMBER：您的 Google Cloud 项目编号。
  • REGION：服务所在的区域。
  • SERVICE_NAME：Cloud Run 代理服务的名称。如果您的服务使用服务账号而不是代理身份，请将 --member 设置为 serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.。

确认 Cloud Run 服务代理可以访问您的 VPC 网络。默认情况下，roles/run.serviceAgent 包含这些权限。如果您修改了服务代理权限，请授予 roles/compute.networkUser：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod." \
    --role="roles/compute.networkUser"

更新 Secure Web Proxy 网关会破坏 Envoy 隧道

更新现有安全 Web 代理网关的 ServerTlsPolicy、证书、IP 地址或端口后，出站请求失败，并显示 502、503 或 504 错误，或者 envoy_sidecar_log 报告 RESPONSE_FLAGS: UF。

创建 Secure Web Proxy 网关后，您无法更改 addresses 或 ports。此外，对现有 Secure Web Proxy 网关上的 serverTlsPolicy 或 certificateUrls 的更新不会传播到 Traffic Director API 中的 EgressRouting 端点。

如需在不造成工作负载停机的情况下更改这些 Secure Web Proxy 字段，请完成以下步骤：

  1. 使用其他资源名称和更新后的配置创建替换 Secure Web Proxy 网关。
  2. 更新 AgentGateway 资源中的 selfManaged.resourceUris，以引用替换 Secure Web Proxy 网关 URI。
  3. 重新创建 EgressRouting 资源，以指向替换 Secure Web Proxy 网关。
  4. 在替换网关路由流量后，从 AgentGateway 资源中移除旧的 Secure Web Proxy 网关，并删除旧的 Secure Web Proxy 网关。

Secure Web Proxy 拒绝所有出站流量

在您创建 EgressRouting 政策或附加 ExtensionBinding 后，来自 Cloud Run 代理的所有出站请求都会失败，并显示 403 错误。

默认情况下，Secure Web Proxy 会拒绝所有流量，直到 Agent Gateway 资源上的 ALLOW AuthzPolicy 允许该流量。附加 ExtensionBinding 不允许没有 ALLOW AuthzPolicy 的流量，并且附加到底层 Secure Web Proxy Gateway 资源的政策会被忽略。

如需允许已获授权的流量，请附加一个以 Agent Gateway 资源为目标的 ALLOW AuthzPolicy。如需查看相关说明，请参阅允许基准出站流量和 MCP 流量。

出站模型请求失败，并显示 403 错误

在 Agent Gateway 上配置政策后，从 Cloud Run 代理到模型端点（例如 REGION-aiplatform.googleapis.com 处的 Vertex AI）的外拨调用失败，并出现 403 Forbidden 错误。

由于 --vpc-egress=all 会通过 Secure Web Proxy 路由所有出站容器流量，因此如果您的 ALLOW AuthzPolicy 仅匹配 Model Context Protocol (MCP) 方法，或者您的 Identity-Aware Proxy (IAP) ExtensionBinding 匹配非 MCP 主机，且您的 Identity and Access Management (IAM) Unified Access Policy 中没有允许规则，则模型请求会失败。

如需允许出站模型调用，请在 Agent Gateway 资源上的 ALLOW AuthzPolicy 中允许模型端点。此外，请在 IAP ExtensionBinding 中将 matchConditions 的范围限定为 prefix: "urn:mcp"，或在 IAM Unified Access Policies 中添加 destination.unregistered.host 允许规则。如需查看相关说明，请参阅允许基准出站流量和 MCP 流量以及配置 IAP 出站流量政策。

Secure Web Proxy 会忽略 GatewaySecurityPolicyRules

您在 Secure Web Proxy Gateway 资源上创建了 GatewaySecurityPolicyRules 或附加了 AuthzPolicy，但它们对出站代理流量没有影响。

当 Secure Web Proxy 与 AgentGateway 资源关联时，Secure Web Proxy 仅强制执行附加到 AgentGateway 资源的授权政策和扩展程序绑定。附加到底层 Secure Web Proxy Gateway 的任何 GatewaySecurityPolicyRules 或 AuthzPolicy 资源都会被忽略。

请改为将 AuthzPolicy 和 ExtensionBinding 资源附加到 Agent Gateway 资源。如需查看相关说明，请参阅在 Agent Gateway 上配置政策。

出站请求未通过 TLS 检查

来自 Cloud Run 代理的出站请求在每次连接时都会失败，并显示 TLS 错误。

Secure Web Proxy 服务账号在 Certificate Authority Service 池中缺少 roles/privateca.certificateManager。

将 CA 池的 roles/privateca.certificateManager 授予您的 Secure Web Proxy 服务账号。如需查看相关说明，请参阅创建服务账号。

经过 TLS 检查的出站连接失败，并显示 SSLV3_ALERT_HANDSHAKE_FAILURE 或 RemoteDisconnected

代理发出的出站请求在首次连接到目标主机时失败，并显示 SSLV3_ALERT_HANDSHAKE_FAILURE，或失败并显示 RemoteDisconnected。

在与目标主机的第一个 TLS 检查连接中，Secure Web Proxy 会从 CA Service 铸造并缓存叶证书，这可能会导致暂时性握手错误。默认发送 Connection: close 的 HTTP 客户端（例如 urllib.request.urlopen）在 TLS 拦截期间可能会失败，并显示 RemoteDisconnected。

为防止在代理代码中出现这些错误，请执行以下操作：

  • 使用可重复使用持久连接的 HTTP 客户端，例如 httpx.AsyncClient 或 requests.Session()。
  • 在 HTTP 客户端（例如 httpx.AsyncHTTPTransport(retries=2) 或 urllib3.util.Retry）上配置连接和握手重试。

后续步骤