Resolver problemas do registro de agentes

Nesta página, mostramos como resolver problemas com o Agent Registry.

A cota de taxa da API foi excedida.

Esse problema pode ocorrer se você interagir com a API Agent Registry ou navegar rapidamente pelo Agent Registry no console do Google Cloud :

429 Too Many Requests

Para resolver esse problema, implemente uma espera exponencial nos clientes da 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 globalmente e por região (20 consultas por segundo).

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

Erro de tamanho do payload durante o registro manual

Esse problema pode ocorrer se você registrar manualmente um agente ou servidor MCP: 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 seus 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

Esse problema pode ocorrer se você criar um agente ou servidor MCP em um produto Google Cloud compatível, como o Google Workspace ou o Gemini Enterprise: o recurso não aparece ao chamar 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 outras integrações são preenchidas por jobs em lote off-line executados periodicamente. Se o recurso não aparecer depois de várias horas, verifique as configurações de Uso do serviço do projeto e confira se a API relevante está ativada.

As operações de longa duração parecem travadas

Esse problema pode ocorrer se você implantar agentes ou configurar vinculações complexas: a operação leva muito tempo e parece travada.

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

Resultados vazios ao buscar vinculações disponíveis

Esse problema pode ocorrer se você buscar vinculações disponíveis para um provedor de autenticação: a API retorna um empty array ou um erro de acesso, mesmo que você tenha verificado se a vinculação existe.

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 a que o autor da chamada não tem acesso. Verifique se o principal tem o acesso necessário no provedor de autenticação e a função roles/agentregistry.viewer no projeto.

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

Esse problema pode ocorrer se você tentar baixar um payload de revisão de skill usando a API GetSkillRevision com o parâmetro de consulta ?alt=media. A solicitação falha e retorna um erro semelhante a este:

{
  "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 exige um redirecionamento 302 para fazer o download do arquivo da skill. 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

Você pode encontrar esse problema depois de criar uma nova revisão de habilidade: a revisão transiciona para um estado FAILED e não pode ser carregada pelos 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 frontmatter YAML válido com name e description definidos.
  • Confirme se a carga útil 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 de cada arquivo 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.

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

Esse problema pode ocorrer se você usar comandos gcloud iap web para gerenciar políticas de saída em recursos do Agent Registry:

NOT_FOUND: Requested entity was not found

Para resolver esse problema, verifique se a flag 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 de APIs 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 URI do recurso retornado por gcloud agent-registry [endpoints|mcp-servers|agents] list para confirmar se o caminho do recurso contém /endpoints/, /mcpServers/ ou /agents/. Passar a flag de recurso errada, por exemplo, --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

Esse problema pode ocorrer se você aplicar ou modificar políticas do IAM da Web do Identity-Aware Proxy para recursos do Agent Registry:

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 usuário tem o papel de administrador da política da 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.

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

Esse problema pode ocorrer se você acessar o Agent Registry no console doGoogle Cloud ou usar a CLI gcloud quando autenticado com a federação de identidade de colaboradores.

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

  • "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, faça a autenticação 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 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.