Resolver problemas de conectividade do Gateway de Agente

Este guia ajuda a depurar e resolver problemas de conectividade com a Gemini Enterprise Agent Platform, especialmente ao usar o Gateway de Agente, a identidade do agente, as políticas do Identity and Access Management (IAM) e a autorização delegada com as Service Extensions.

Resolver problemas usando a habilidade de solução de problemas da Agent Platform

Para diagnosticar problemas de conectividade, autorização e inicialização de forma interativa com um assistente de programação de IA, instale a habilidade agent-platform-troubleshooting do repositório de habilidades do agente Cloud de Confiance by S3NS .

Essa habilidade equipa os agentes de IA com playbooks de diagnóstico específicos do domínio, filtros de registro e etapas de resolução em toda a pilha da plataforma de agentes, incluindo:

  • Negações de saída do Gateway de Agente: diagnóstico de erros 403 Forbidden interceptados pelo gateway e verificação das decisões de autorização do IAP.
  • Falhas na inicialização do Agent Runtime: identificação de funções ausentes (como roles/browser ou resourcemanager.projects.get) e exceções de bootstrap.
  • Problemas de destino do Agent Registry: verificação de entradas de serviço, interfaces de endpoint e configurações consolidadas das APIs do Google.
  • Políticas de acesso do IAM: validação de vinculações da política de acesso unificada (UAP), expressões de condição e escopo do limite de acesso de principal (PAB).
  • Confiança do contêiner: diagnóstico de erros de certificado TLS e handshake para contêineres personalizados (BYOC) ou autoridades certificadoras (CAs) particulares.

Para instalar a habilidade no ambiente do agente, execute o seguinte comando:

npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

Fluxo de solicitação de saída

A Agent Platform adota uma política de negação padrão para todo o tráfego de saída. Para que um agente se conecte a recursos externos, você precisa permitir explicitamente o acesso em todas as camadas de rede e identidade. Quando o Gateway de Agente está ativado, ele intercepta todas as solicitações do agente e aplica as políticas configuradas.

Para que uma solicitação seja bem-sucedida, ela precisa atender a todas as seguintes condições:

  • Política de acesso do IAM: a identidade do agente atribuída a ele precisa receber a permissão iap.resources.egressViaIAP no recurso de destino, diretamente ou por um conjunto principal. Para mais detalhes, consulte Criar políticas do agente do IAM. Saiba como resolver problemas de políticas do IAP.
  • Registro de agentes: recomendamos registrar destinos no Registro de agentes para aplicar políticas de acesso granulares por recurso e controles no nível da ferramenta. Se o agente estiver tentando acessar um destino não registrado, conceda a permissão iap.resources.egressViaIAP à identidade do agente configurando uma política para um endpoint não registrado.
  • Gateway de Agente: o gateway precisa estar associado a uma política de autorização que o direcione explicitamente. Por padrão, o gateway usa o IAP e o Model Armor para proteger as solicitações.
  • Autorização delegada com Service Extensions: é possível delegar decisões de autorização a um mecanismo de autorização personalizado usando Service Extensions. Dependendo da política de autorização configurada, um ou mais desses mecanismos de autorização vão permitir ou negar a solicitação.

Problemas comuns

Confira estes problemas comuns e as soluções deles ao resolver problemas do Gateway de Agente.

Erros durante a inicialização do Agent Runtime

Se as instâncias do ambiente de execução do agente não iniciarem ou não forem implantadas, isso pode significar que o IAP está bloqueando o tráfego interno ou que o agente não tem as funções básicas necessárias para inicializar.

  1. Confirmar se a IAP não está bloqueando chamadas para serviços internos

    Sintoma: erros 403 Forbidden durante a inicialização.

    Causa: o gateway de agente usa uma política de negação padrão para todo o tráfego. Portanto, quando a IAP está no modo de aplicação, ela bloqueia chamadas até mesmo para serviços internos (como aiplatform ou logging), a menos que estejam registrados e o agente tenha as permissões necessárias do IAM.

    Correção: mude temporariamente o IAP para o modo de teste para ver quais conexões estão falhando sem bloquear a inicialização ou consulte o Cloud Logging para identificar os nomes de host bloqueados exatos. Depois de identificar os nomes de host do serviço de destino, registre-os no Agent Registry e conceda a permissão iap.resources.egressViaIAP ao agente.

    Para encontrar nomes de host bloqueados específicos usando o Cloud Logging, execute a seguinte consulta na Análise de registros:

    resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
httpRequest.status=403

    Examine os campos httpRequest.requestUrl ou jsonPayload.authzPolicyInfo nos resultados para encontrar os nomes de host de destino.

    Alguns serviços internos comuns que podem exigir registro durante a inicialização incluem:

    • Agent Platform (mecanismo de raciocínio e sessões): https://REGION-aiplatform.mtls.googleapis.com
    • Resource Manager: https://cloudresourcemanager.mtls.googleapis.com e https://cloudresourcemanager.mtls.googleapis.com/
    • Google Cloud Observability (se ativado): https://telemetry.mtls.googleapis.com/
    • Cloud Logging (se ativado): https://logging.googleapis.com/
    • Cloud Monitoring: https://monitoring.googleapis.com/ e https://monitoring.mtls.googleapis.com/
    • Cloud Trace: https://cloudtrace.googleapis.com/ e https://cloudtrace.mtls.googleapis.com/
    • Secret Manager: https://secretmanager.googleapis.com/ e https://secretmanager.mtls.googleapis.com/

  2. Confirme se a identidade do agente tem os papéis básicos necessários

    Sintomas: nos registros do aiplatform.googleapis.com/reasoning_engine_stderr, você vê erros como google.api_core.exceptions.Unknown: None ou Failed to convert project number to project ID. O erro aparece durante a inicialização do Reasoning Engine.

    Causa. A identidade do agente não tem a permissão resourcemanager.projects.get necessária para resolver o nome do projeto durante a inicialização.

    Correção. Verifique se a identidade do agente (ou o conjunto principal) tem as permissões necessárias para ler a própria configuração de tempo de execução. Os seguintes papéis são necessários:

    • roles/aiplatform.agentDefaultAccess: papel padrão do agente.
    • roles/aiplatform.user: necessário para executar o agente.
    • roles/agentregistry.viewer: obrigatório para visualizar recursos registrados.
    • roles/logging.logWriter e roles/monitoring.metricWriter: obrigatórios para observabilidade.
    • roles/browser: obrigatório para executar resourcemanager.projects.get durante a inicialização do SDK.

    Para verificar os papéis atribuídos à identidade do agente, execute o seguinte comando:

    gcloud projects get-iam-policy PROJECT_ID \
--flatten="bindings[].members" \
--filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"

    Substitua:

    • PROJECT_ID: o ID do projeto do Cloud de Confiance .
    • AGENT_IDENTITY_PRINCIPAL: o principal da identidade do agente. Usa o formato: principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH

    Para saber como conceder papéis, consulte Usar a identidade do agente com o Agent Runtime.

403 Forbidden erros

Se você encontrar um erro 403 Forbidden, confirme se ele está relacionado à saída do Gateway de Agente. Confira um exemplo de mensagem de erro de saída:

{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}

Consulte os registros do agente no Logging para encontrar as chamadas com falha específicas:

resource.type="aiplatform.googleapis.com/ReasoningEngine"
resource.labels.location="LOCATION"
resource.labels.reasoning_engine_id="AGENT_ID"
textPayload:"403"

Substitua:

  • LOCATION: a região em que o agente é implantado, por exemplo, us-central1.
  • AGENT_ID: o ID do agente (mecanismo de raciocínio).

Procure a mensagem Egress request is not authorized no textPayload da entrada de registro. Se o erro 403 contiver um texto diferente, o serviço de destino poderá estar rejeitando a chamada diretamente, em vez do Agent Gateway.

Também é possível conferir os registros de tráfego de saída, incluindo negações de 403, usando o painel de observabilidade integrado.

Destinos de CA autoassinados ou particulares não se conectam

  • Sintoma:o agente não consegue se conectar a destinos que apresentam certificados autoassinados ou emitidos por uma CA particular.
  • Causa:por padrão, o Agent Gateway confia apenas em certificados emitidos por CAs publicamente confiáveis. A conexão com destinos que usam CAs particulares ou certificados autoassinados exige configuração adicional.
  • Mitigação:para se conectar a destinos usando CAs particulares ou certificados autoassinados, configure âncoras de confiança TLS personalizadas usando a configuração tlsConfig em um modelo de conectividade do agente.

O agente implantado com contêiner personalizado (BYOC) não se conecta ao Gateway de Agente

  • Sintoma:o agente BYOC não consegue estabelecer conexões quando roteado pelo Agent Gateway. Os registros podem mostrar erros de handshake TLS ou de verificação de certificado.
  • Causa:o contêiner personalizado do agente não confia na autoridade certificadora do Gateway de Agente.
  • Correção:adicione o certificado raiz do Gateway de Agente ao repositório de CA do contêiner. Consulte Configurar agentes de contêiner personalizado (BYOC) para o Gateway de Agente.

A vinculação de política falha ou imita uma negação de governança

  • Sintoma:as configurações de vinculação de políticas falham, você recebe uma solicitação interativa de um etag ao vincular políticas ou as solicitações falham com um erro falso de negação de governança (como "destino não registrado rejeitado corretamente").
  • Causa:a API Identity-Aware Proxy (iap.googleapis.com) está desativada no seu projeto.
  • Correção:ative a API Identity-Aware Proxy.

Falhas ao gerenciar o Gateway de Agente com a federação de identidade de colaboradores

Esse problema pode ocorrer se você gerenciar o Gateway de Agente no console doCloud de Confiance ou usar a CLI gcloud quando autenticado com a federação de identidade de colaboradores (WIF).

O console mostra erros genéricos de carregamento ou criação, como os seguintes:

  • "Ocorreu um erro ao carregar..."
  • "O servidor não conseguiu atender à solicitação"
  • "Falha ao criar gateway de agente"
  • "Falha ao carregar"

Além disso, comandos gcloud (como gcloud network-services agent-gateways import) podem retornar um erro interno, como error 13: an internal error has occurred.

Para resolver esse problema, autentique-se com uma Conta do Google padrão gerenciada pelo Cloud Identity ou pelo Google Workspace que tenha as permissões necessárias, como roles/networkservices.admin.

As identidades federadas têm suporte limitado na governança da plataforma de agentes e nos serviços do Gateway em prévia. Conceder papéis mais amplos do IAM a um principal federado não resolve o problema.

Fluxo de trabalho de depuração

Se alguma das condições descritas na seção Fluxo de solicitação de saída estiver faltando, suas solicitações poderão ser bloqueadas.

Analisar a decisão do IAP

Para restringir a pesquisa de registros às decisões de saída do IAP, execute a seguinte consulta no Logging:

protoPayload.serviceName="iap.googleapis.com"
protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
protoPayload.metadata.mcp_attributes.base_protocol_method="true"

Se você não encontrar uma entrada de registro do IAP correspondente, talvez o gateway tenha negado a solicitação antes que o IAP a avaliasse. Siga para a próxima etapa.

Se você encontrar uma entrada de registro correspondente, revise os seguintes campos:

  • protoPayload.authorizationInfo[].granted: indica se a solicitação foi permitida (true) ou negada (false).
  • protoPayload.authenticationInfo.principalSubject: o ID do SPIFFE ou a identidade principal://... do autor da chamada. Verifique se isso corresponde à identidade do seu agente.
  • protoPayload.authorizationInfo[].resource: o recurso de destino registrado que a chamada resolveu.
  • labels."iap.googleapis.com/audited_resource_name": se esse valor for unregisteredResource, o nome do host de destino não será registrado. Registre o nome do host de destino no Agent Registry e verifique se o agente tem a permissão iap.resources.egressViaIAP para esse destino.
  • Modo de aplicação: revise o modo de aplicação da solicitação. Para filtrar solicitações de simulação, adicione protoPayload.metadata.iamEnforcementMode="DRY_RUN" à consulta. No modo DRY_RUN, o IAP registra as negações, mas não as aplica. Portanto, se o agente falhar com um erro 403 no modo de simulação, a negação provavelmente virá do proxy de saída do gateway ou do recurso de destino.

Analisar a decisão do Gateway de Agente

Para analisar como o Agent Gateway avaliou a solicitação, consulte os registros do gateway no Logging. Neste exemplo, estamos filtrando os registros apenas para erros 403:

resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"
httpRequest.status=403
-httpRequest.requestMethod="CONNECT"

Revise os seguintes campos na entrada de registro correspondente:

  • jsonPayload.authzPolicyInfo.policies.result: o resultado geral da autorização, ALLOWED ou DENIED.
  • httpRequest.requestUrl: anote o URL de destino exato que o agente tentou acessar. Na próxima etapa, vamos verificar se o nome do host usado pelo recurso de destino foi registrado no Agent Registry.

Verificar o registro do destino e a cobertura da política de acesso do IAM

O acesso aos destinos sempre exige uma política de permissão do IAM que conceda a permissão iap.resources.egressViaIAP à identidade do agente. Recomendamos registrar destinos no Agent Registry para aplicar políticas de acesso granulares por recurso e garantir a correspondência precisa de nomes de host. Para destinos que não estão registrados, verifique se uma política para endpoints não registrados concede a permissão necessária à identidade do agente.

Se você usa políticas por recurso, todos os nomes de host de destino e as variações do nome do host que o agente tenta alcançar precisam ser registrados no Agent Registry. Isso ocorre porque uma API do Google, como aiplatform.googleapis.com, pode ser resolvida por vários nomes de host, dependendo da versão do SDK, da configuração regional do cliente ou do uso de mTLS (por exemplo, us-central1-aiplatform.googleapis.com ou us-central1-aiplatform.mtls.googleapis.com).

Como o gateway faz a correspondência exata dos nomes de host, se você registrar aiplatform.googleapis.com, mas o agente chamar us-central1-aiplatform.googleapis.com, o gateway vai considerar o recurso como não registrado e negar a solicitação.

Execute o script de exemplo a seguir para listar as entradas do registro com base no tipo de recurso e verifique as entradas do nome do host específico usado pela chamada do agente:

HOSTNAME="HOSTNAME"
PROJECT_ID="PROJECT_ID"
LOCATION="REGION"

echo "Checking Endpoints..."
gcloud agent-registry endpoints list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking MCP Servers..."
gcloud agent-registry mcp-servers list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking Agents..."
gcloud agent-registry agents list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

Substitua:

  • HOSTNAME: o nome do host de destino que o agente está tentando alcançar, por exemplo, us-central1-aiplatform.mtls.googleapis.com.
  • PROJECT_ID: o ID do projeto do Cloud de Confiance .
  • REGION: o local dos recursos do Agent Registry e do Gateway de Agente, por exemplo, us-central1.

Saída 1: o nome do host já está registrado

Se o nome do host existir em uma entrada do Agent Registry, você verá uma saída semelhante ao exemplo a seguir:

Checking Endpoints...
  url: https://us-central1-aiplatform.mtls.googleapis.com
Checking MCP Servers...
Checking Agents...

Acesse Verificar vinculações do IAM no recurso de destino para conferir se uma política por recurso ou em todo o registro concede acesso à identidade do agente.

Saída 2: o nome de host não existe no registro

Se o nome do host não existir no registro, você verá uma saída semelhante ao exemplo a seguir:

Checking Endpoints...
Checking MCP Servers...
Checking Agents...

Se você planeja usar políticas por recurso ou em todo o registro, registre o destino no Agent Registry primeiro. Se você usar políticas para endpoints não registrados, prossiga para Verificar as vinculações do IAM no recurso de destino.

Verificar as vinculações do IAM no recurso de destino

Verifique se a identidade do agente ou o conjunto principal dele tem a permissão iap.resources.egressViaIAP no destino.

É possível configurar vinculações de políticas em três escopos:

  • Em todo o registro: acesso a todos os agentes, servidores MCP e endpoints registrados no registro.
  • Por recurso: acesso restrito. Uma vinculação por recurso substitui a vinculação em todo o registro para esse recurso específico, em vez de mesclar com ela.
  • Políticas para endpoints não registrados: acesso a destinos que não estão registrados no Agent Registry.

Use um dos seguintes exemplos para verificar as vinculações:

  • Para verificar as vinculações de política do IAM no nível do registro, execute o seguinte comando:

    curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \
-H "Content-Type: application/json"

  • Para verificar as vinculações de política do IAM por endpoint, execute o comando a seguir:

    export HOSTNAME=HOSTNAME

ENDPOINT_ID=$(gcloud agent-registry endpoints list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$HOSTNAME" \
--format="value(name.basename())")

echo "ENDPOINT_ID=$ENDPOINT_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"

    Substitua HOSTNAME pelo nome do host do destino que o agente está tentando alcançar, por exemplo, us-central1-aiplatform.mtls.googleapis.com.

  • Para verificar as vinculações de políticas do IAM por servidor do MCP, execute o comando a seguir:

    export MCP_SERVER=MCP_SERVER

MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$MCP_SERVER" \
--format="value(name.basename())")

echo "MCP_SERVER_ID=$MCP_SERVER_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"

    Substitua MCP_SERVER pelo URL do servidor MCP (por exemplo, https://example-abc12345-uc.a.run.app/mcp).

Nas informações da política retornada, procure uma vinculação com a permissão iap.resources.egressViaIAP que corresponda à identidade do agente ou ao conjunto de principais. Se a saída retornada contiver um campo "etag", mas nenhuma vinculação, isso significa que não há uma política do IAM.

Se houver uma vinculação, mas ela incluir um condition, verifique se a expressão da Common Expression Language (CEL) não está excluindo o agente. Uma condição que filtra por um atributo que o agente não tem pode estar excluindo o agente sem aviso.

Se o destino não tiver uma vinculação de política de correspondência que conceda a permissão iap.resources.egressViaIAP à identidade do agente ou ao conjunto de principais, conceda a permissão usando uma das seguintes opções de política:

Inspecionar a política de autorização e a extensão

Nesta seção, vamos garantir que haja uma política de autorização direcionada explicitamente ao Gateway de Agente associado ao agente.

  1. Confira os detalhes da extensão de autorização associada ao gateway e confirme se a extensão que você está usando está configurada conforme o esperado.

    gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Substitua AUTHORIZATION_EXTENSION_NAME pelo nome da extensão associada ao gateway. Se você não souber o nome da extensão, acesse a página de detalhes do gateway no console Cloud de Confiance Cloud de Confiance e anote o valor do campo Nome da extensão em Extensões de serviço.

  2. Verifique se uma política de autorização segmenta explicitamente o recurso de gateway e se vincula à mesma extensão de autorização. Navegue até a página de detalhes do gateway no console do Cloud de Confiance Cloud de Confiance e anote o valor do campo Nome da política em Extensões de serviço.

    Se nenhuma política for direcionada ao gateway ou se o mapeamento de gateway para política estiver incorreto, a extensão de autorização não será executada.

Verificar políticas de limite de acesso principal

As políticas de limite de acesso de principal têm precedência sobre as políticas de permissão do IAM. Isso significa que, mesmo que você tenha configurado corretamente todas as vinculações do IAM, uma solicitação vai falhar se houver uma política de limite de acesso de principal ativa que exclua o recurso de destino do escopo do agente.

Para listar políticas em toda a organização, execute:

gcloud iam principal-access-boundary-policies list \
  --organization="ORGANIZATION_ID" \
  --location=global

Para encontrar políticas vinculadas ao conjunto de principais do agente, execute:

gcloud iam policy-bindings search-target-policy-bindings \
  --project="PROJECT_ID" \
  --target="PRINCIPAL_SET"

Substitua:

  • ORGANIZATION_ID: o ID da sua Cloud de Confiance organização.
  • PROJECT_ID: o ID do projeto do Cloud de Confiance .
  • PRINCIPAL_SET: o conjunto principal da identidade do agente.

Se houver uma vinculação, inspecione o campo details.rules[].resources[] para verificar se o destino está no escopo do agente.

Testar vinculações principais x conjunto principal

Se as permissões funcionarem de maneira inconsistente ou falharem inesperadamente, o problema pode estar relacionado à forma como a identidade do grupo do agente (o conjunto principal) está configurada. As permissões baseadas em conjuntos de principais podem falhar pelos seguintes motivos:

  • Atrasos na sincronização: quando você adiciona uma identidade a um conjunto, pode levar alguns minutos para que o IAM atualize e reconheça o novo membro.
  • Atributos ausentes: se a participação em um conjunto principal exigir determinados atributos, a identidade do agente precisará ter exatamente esses atributos (por exemplo, rótulos de departamento ou equipe). Se a identidade não tiver esses atributos, o agente poderá ser excluído silenciosamente do grupo.

Para testar se a associação ao grupo é o problema, conceda permissões diretamente ao agente específico adicionando uma vinculação principal:// direta ao recurso afetado. Se o agente se conectar com a vinculação direta, a causa raiz provavelmente será uma incompatibilidade de atributos ou um atraso de sincronização com o conjunto de principais. Para resolver isso, verifique e corrija os atributos de identidade do agente ou use vinculações diretas de principal://.

A seguir

Codelab

Aprenda a governar cargas de trabalho com agentes com o Gateway de Agente na Gemini Enterprise Agent Platform.

Guia

Saiba como monitorar o Gateway de Agente.