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 do Registro de agentes ou navegar rapidamente pelo Registro de agentes no Google Cloud console:

429 Too Many Requests

Para resolver esse problema, implemente a espera exponencial nos clientes da API para gerenciar as taxas de solicitação. A API do 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 as guias no Google Cloud console, 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

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 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

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 após várias horas, verifique as configurações de Service Usage do projeto e se a API relevante está ativada.

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 tempos de operação de longa duração (LRO) que podem levar até 30 minutos. Configure as configurações de tempo limite do cliente e consulte a 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 uma empty array ou um erro de acesso, mesmo que você tenha verificado se a vinculação existe.

Para resolver esse problema, verifique se a entidade principal tem as permissões corretas do Identity and Access Management (IAM) no recurso AuthProvider de destino. A API aplica verificações de IAM rigorosas e remove objetos Binding que referenciam provedores de autenticação a que o autor da chamada não tem acesso. Verifique se a entidade 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 habilidades falha com o erro 302

Esse problema pode ocorrer se você tentar fazer o download de um payload de revisão de habilidades usando a API GetSkillRevision com o parâmetro de consulta ?alt=media: a solicitação falha e retorna um erro semelhante ao seguinte:

{
  "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 habilidade. Por exemplo, se você estiver usando curl, adicione a flag -L ou --location ao comando.

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

Esse problema pode ocorrer depois de criar uma nova revisão de habilidades: 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 frontmatter 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 percurso de diretório, como .., ou caminhos absolutos.