Resolver problemas do registro de agentes

Ao registrar, descobrir ou conectar componentes no Agent Registry, é possível diagnosticar e resolver problemas comuns, como limites de cota, erros de validação de payload e habilidade, incompatibilidades de local, atrasos de sincronização e erros de permissão.

A cota de taxa da API foi excedida

O erro a seguir ocorre se você exceder o limite de taxa de solicitação ao interagir com a API Agent Registry ou navegar rapidamente pelo Agent Registry no console doGoogle Cloud :

429 Too Many Requests

Para resolver esse problema, implemente a espera exponencial nos clientes de API para gerenciar as taxas de solicitação. A API Agent Registry tem uma cota de taxa padrão de 1.200 solicitações por minuto, ou 20 consultas por segundo, globalmente e por região.

Se você encontrar limitação ao alternar guias no console do Google Cloud , aguarde alguns instantes e tente novamente. Se o caso de uso programático exigir limites mais altos, solicite um aumento de cota para a métrica RequestsPerMinute.

Erro de tamanho do payload durante o registro manual

O erro a seguir ocorre quando você registra manualmente um agente ou servidor MCP com um arquivo de especificação que excede o limite de tamanho:

A API rejeita a solicitação com um erro informando que o payload é muito grande.

Para resolver esse problema, verifique se o arquivo agent-card.json ou toolspec.json tem menos de 10 KB. Os tamanhos de conteúdo AgentSpec e McpServerSpec são limitados a 10 KB. Minifique os arquivos JSON, remova espaços em branco desnecessários ou condense as descrições das ferramentas para obedecer a esse limite. Para mais informações, consulte Esquemas JSON.

Agentes ou servidores MCP ausentes após a criação

O erro a seguir ocorre depois que você cria um agente ou servidor MCP em um produto compatível do Google Cloud , como o Google Workspace ou o Gemini Enterprise:

O recurso não aparece na saída quando você chama as APIs ListAgents ou ListMcpServers.

Para resolver esse problema, aguarde a conclusão da sincronização em segundo plano. Seus recursos são atualizados em tempo real, mas jobs em lote off-line periódicos preenchem outras integrações. Se o recurso não aparecer depois de várias horas, verifique as configurações de Service Usage do projeto e confirme se a API relevante está ativada.

Operações de longa duração parecem travadas

O seguinte erro ocorre quando você implanta agentes ou configura vinculações complexas:

A operação leva muito tempo e parece travada.

Para resolver esse problema, use a ferramenta get_operation MCP ou o endpoint de API google.longrunning.Operations.GetOperation para consultar o status da operação. Algumas criações de agentes e back-ends de MCP exigem um provisionamento de infraestrutura significativo, o que pode levar a tempos de operação de longa duração (LRO) de até 30 minutos. Configure as definições de tempo limite do cliente como resultado e consulte a flag booleana done para verificar a conclusão.

Resultados vazios ao buscar vinculações disponíveis

O erro a seguir ocorre se você buscar vinculações disponíveis para um provedor de autenticação sem permissões suficientes no recurso AuthProvider de destino:

A API retorna uma matriz vazia ou um erro de acesso, mesmo que a vinculação exista.

Para resolver esse problema, verifique se o principal tem as permissões corretas do Identity and Access Management (IAM) no recurso AuthProvider de destino. A API aplica verificações rigorosas do IAM e remove objetos Binding que fazem referência a provedores de autenticação aos quais o autor da chamada não tem acesso. Verifique se o principal tem o acesso necessário no provedor de autenticação e o papel roles/agentregistry.viewer no projeto.

O download da revisão de habilidade falha com o erro 302

O erro a seguir vai ocorrer se você tentar fazer o download de um payload de revisão de habilidade usando a API GetSkillRevision com o parâmetro de consulta ?alt=media e seu cliente HTTP não seguir os redirecionamentos:

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

Para resolver esse problema, verifique se o cliente HTTP está configurado para seguir redirecionamentos automaticamente. O endpoint ?alt=media requer um redirecionamento 302 para fazer o download do arquivo da habilidade. Por exemplo, se você estiver usando curl, adicione a flag -L ou --location ao comando.

A validação da revisão da habilidade falha ou mostra o estado FAILED

O erro a seguir ocorre quando você cria uma nova revisão de habilidade com um arquivo ZIP inválido:

A revisão faz a transição para um estado FAILED e não pode ser carregada por agentes.

Para resolver esse problema, verifique os registros de validação ou inspecione o conteúdo do payload ZIP:

  • Verifique se o arquivo ZIP contém um arquivo SKILL.md na raiz.
  • Verifique se o arquivo SKILL.md tem um bloco de front matter YAML válido com name e description definidos.
  • Confirme se o payload ZIP não excede os limites de tamanho: o tamanho compactado precisa ser menor que 500 KB, o tamanho total descompactado menor que 10 MB e o tamanho do arquivo individual menor que 1 MB.
  • Verifique se o arquivo não contém links simbólicos, elementos de travessia de diretório, como .., ou caminhos absolutos.

As habilidades independentes não aparecem nas listas de recursos de serviço ou de agente

O erro a seguir vai ocorrer se você consultar as listas de agentes ou serviços para habilidades independentes, como ao executar gcloud agent-registry services list ou gcloud agent-registry agents list:

A habilidade independente não aparece na saída.

Para resolver esse problema, consulte a coleção skills:

  • Ao contrário de agentes, servidores MCP e endpoints registrados manualmente, as habilidades independentes não usam recursos graváveis de Service ou recursos de descoberta de Agent, McpServer ou Endpoint. Em vez disso, o Agent Registry representa habilidades independentes diretamente como recursos Skill de nível superior e recursos SkillRevision com controle de versão.
  • Para listar, pesquisar ou inspecionar habilidades independentes, use a guia Habilidades no console doGoogle Cloud , execute gcloud alpha agent-registry skills list ou gcloud alpha agent-registry skills search ou chame os métodos da API REST skills. Para ver instruções, consulte Gerenciar habilidades e Pesquisar habilidades independentes.
  • Se você estiver procurando habilidades de A2A inline declaradas no card de um agente, inspecione o campo skills no recurso de descoberta Agent usando gcloud agent-registry agents describe ou gcloud agent-registry agents search.

Erro de entidade de recurso não encontrada ao gerenciar políticas do IAP

O erro a seguir ocorre quando você usa comandos gcloud iap web para gerenciar políticas de saída do Identity-Aware Proxy (IAP) em recursos do Agent Registry:

NOT_FOUND: Requested entity was not found

Para resolver esse problema, verifique o seguinte:

  • Status do registro: confirme se o componente de destino está registrado no Agent Registry no local esperado.
  • Formato do identificador: confirme se o comando ou a vinculação de política especifica o nome do recurso padrão, em vez de um URN de identificador de registro.
  • Sinalização de recurso: verifique se a sinalização de recurso transmitida para gcloud iap web corresponde ao tipo de recurso filho do Agent Registry:
    • Para endpoints, como APIs externas ou pontos de saída da API do Google, use a flag --endpoint.
    • Para servidores do Protocolo de Contexto de Modelo, use a flag --mcp-server.
    • Para agentes registrados, use a flag --agent.

Verifique o nome do recurso retornado por gcloud agent-registry endpoints list, gcloud agent-registry mcp-servers list ou gcloud agent-registry agents list para confirmar se o nome do recurso contém /endpoints/, /mcpServers/ ou /agents/. Transmitir a flag de recurso errada, por exemplo, transmitir --endpoint para um ID de servidor MCP, causa um erro NOT_FOUND.

Permissão negada ao aplicar políticas do IAM da Web do IAP

O erro a seguir ocorre quando você aplica ou modifica as políticas do IAM da Web do IAP para recursos do Agent Registry sem os papéis administrativos necessários:

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

Para resolver esse problema, verifique se o usuário ativo ou a conta de serviço tem as permissões necessárias no projeto que hospeda o registro e o gateway:

  • Verifique se o autor da chamada tem o papel de Administrador de políticas do IAP (roles/iap.admin) ou Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto de governança central.
  • Confirme se o autor da chamada tem as permissões iap.web.setIamPolicy e resourcemanager.projects.setIamPolicy.

Servidor MCP remoto não encontrado em um local regional

O erro a seguir ocorre se você consultar um servidor MCP remoto do Google ou do Google Cloud registrado automaticamente ou aplicar uma política de saída do IAP a ele em um local regional, como us-central1:

A solicitação retorna um erro NOT_FOUND ou uma lista vazia, mesmo quando o serviço fornece endpoints regionais (REPs) ou quando o tráfego é roteado por um Gateway de Agente regional.

Quando o Agent Registry registra automaticamente um servidor MCP do Google ou Google Cloud para uma API ativada, ele cria o recurso McpServer apenas no local global, não em regiões individuais, como us-central1. Se o serviço fornecer endpoints regionais, como https://SERVICE.REGION.rep.googleapis.com/mcp, o Agent Registry vai listar esses URLs regionais no campo interfaces desse único recurso global McpServer.

Para resolver o problema, siga um destes procedimentos:

  • Use global para servidores registrados automaticamente: especifique o local global ao consultar o servidor no Agent Registry com --location=global ou aplique políticas de saída do IAP a ele com --region=global, mesmo quando o agente de chamada roteia o tráfego por um gateway regional.
  • Registrar em uma região para residência de dados: se você precisar manter os metadados do registro em uma região específica, implante servidores MCP personalizados em ambientes de execução regionais do Cloud Run ou do Google Kubernetes Engine (GKE), ou registre manualmente o servidor MCP e o URL do endpoint regional nessa região e, em seguida, aplique sua política do IAP nessa mesma região. Quando o Gateway de Agente resolve um URL de destino, as entradas de registro regional têm precedência sobre as entradas global.

Erros de incompatibilidade de região ao configurar o Model Armor no Gateway de Agente

O erro a seguir ocorre quando você configura filtros de política do Model Armor no Gateway de Agente em regiões incompatíveis:

A criação da política de autorização falha com um erro de incompatibilidade de região, ou o tráfego roteado pelo gateway para um servidor MCP falha na avaliação da política.

Para resolver esse problema, verifique o alinhamento regional dos recursos do gateway e as vinculações de política de destino:

  • Alinhar as regiões do gateway e do Model Armor: verifique se o Gateway de Agente, os modelos do Model Armor, a extensão de autorização e a política estão todos na mesma região, como us-central1.
  • Rotear para servidores MCP global ou regionais: não é necessário registrar novamente os servidores MCP global em uma região apenas para usar o Model Armor. Como o Model Armor inspeciona os payloads de solicitação e resposta no gateway regional, ele pode inspecionar e controlar o tráfego roteado para servidores MCP registrados no local global, além de destinos regionais.
  • Corresponder as vinculações de saída do IAP ao local de registro do destino: aplique a vinculação de autorização de saída do IAP no local em que o recurso McpServer de destino está registrado. Use global para servidores MCP remotos registrados automaticamente ou use a região específica para servidores MCP registrados regionalmente.

Falha no registro manual ou na criação de vinculação em um local multirregional

O erro a seguir ocorre se você tentar registrar manualmente um agente, um servidor MCP ou um endpoint, ou criar uma vinculação, em um local multirregional, como us ou eu:

A API rejeita a solicitação com um erro de local não compatível ou argumento inválido.

Para resolver esse problema, especifique uma região com disponibilidade compatível, como us-central1 ou europe-west1, ou o local global. Os locais multirregionais us e eu só são compatíveis com a descoberta de componentes registrados automaticamente e o registro ou a descoberta de habilidades independentes. Para ver a lista de locais compatíveis, consulte Locais do Agent Registry.

Falhas ao acessar o Agent Registry com a federação de identidade de colaboradores

Os erros a seguir ocorrem se você acessar o Agent Registry no console doGoogle Cloud ou usar a Google Cloud CLI quando autenticado com a federação de identidade de colaboradores:

O console doGoogle Cloud mostra erros de carregamento genéricos, como:

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

Além disso, os comandos gcloud 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. Verifique se a conta tem as permissões necessárias, como roles/agentregistry.admin ou roles/agentregistry.viewer.

Os serviços de governança da Gemini Enterprise Agent Platform têm suporte limitado para identidades federadas. Conceder papéis mais amplos do IAM a um principal federado não resolve o problema.