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 da API para gerenciar as taxas de solicitação. A API Agent Registry tem cotas de taxa padrão de solicitações por minuto por local que se aplicam aos recursos do Agent Registry.

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 um tempo significativo 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 do 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 passa 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 1 MB, 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 ocorre 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 Service graváveis ou recursos de descoberta 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 agent-registry skills list ou gcloud 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 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.
  • Flag de recurso: 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 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 Google Cloud remoto ou do Google para uma API ativada, ele cria o McpServer recurso 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 seguinte erro 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.

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.

Download da revisão de habilidade bloqueado devido a descobertas de segurança

O erro a seguir vai ocorrer se você tentar fazer o download de um payload de revisão de habilidade quando a política de verificação da habilidade estiver definida como ENABLED_BLOCKING e a revisão tiver descobertas de segurança:

FAILED_PRECONDITION: cannot download skill revision with scan findings when scanning policy is ENABLED_BLOCKING

Para resolver o problema, siga um destes procedimentos:

  1. Inspecione as descobertas de segurança detectadas na revisão executando o comando gcloud agent-registry findings list. Esse comando requer o papel roles/agentregistry.admin.
  2. Corrija a descoberta nos arquivos de origem locais, como remover o código de saída de rede não autorizado, remover credenciais expostas ou eliminar padrões de injeção de comandos.
  3. Fazer upload e registrar uma nova revisão de habilidade.
  4. Como alternativa, se você estiver trabalhando em um ambiente de teste ou de preparo autorizado, atualize a política de verificação da habilidade para ENABLED_NONBLOCKING usando --scanning-policy=enabled-nonblocking. Para mais informações, consulte Verificar habilidades em busca de problemas de segurança.

Falha ao definir a revisão padrão ou ativar a política de bloqueio

O erro a seguir vai ocorrer se você atualizar o ponteiro de revisão padrão de uma habilidade (--default-revision) ou mudar a política de verificação de uma habilidade para ENABLED_BLOCKING quando a revisão tiver descobertas ou resultados de verificação pendentes:

A API retorna um erro FAILED_PRECONDITION com uma das seguintes mensagens:

  • cannot set default revision to a revision with scan findings when scanning policy is ENABLED_BLOCKING
  • cannot set default revision to a revision with pending scan results when scanning policy is ENABLED_BLOCKING
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has scan findings
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has pending scan results

Para resolver esse problema, faça o seguinte:

  • Se a verificação ainda estiver pendente (RUNNING), aguarde a conclusão da verificação em segundo plano e verifique se scanResult.scanState é resolvido como SUCCEEDED sem findings antes de definir a revisão como padrão ou ativar ENABLED_BLOCKING.
  • Se a revisão padrão atual ou de destino tiver descobertas de segurança, publique uma nova revisão com os problemas de segurança resolvidos, verifique se o scanResult.scanState é resolvido como SUCCEEDED sem findings listado e defina essa revisão limpa como defaultRevision da habilidade.

A revisão da habilidade foi rejeitada devido aos limites de tamanho não compactado

O erro a seguir ocorre quando você faz upload de uma revisão de habilidade que excede os limites máximos de tamanho de verificação não compactada:

A operação de longa duração falha com um erro INVALID_ARGUMENT ou o scanResult.scanState da revisão faz a transição para UNSUPPORTED_FORMAT.

Para resolver o problema, siga um destes procedimentos:

  • Inspecione os arquivos descompactados no pacote ZIP. Remova conjuntos de dados grandes, binários de modelo ou recursos desnecessários para manter cada arquivo com menos de 1 MB e o pacote extraído total com menos de 10 MB.
  • Se o fluxo de trabalho de desenvolvimento exigir o upload de arquivos grandes para prototipagem rápida em um projeto, atualize a política de verificação da habilidade para DISABLED usando --scanning-policy=disabled, se permitido pela política da organização.

Não é possível desativar a verificação de habilidades devido à política da organização

O erro a seguir vai ocorrer se você criar ou atualizar uma habilidade com a política de verificação definida como DISABLED ou se atualizar qualquer campo em uma habilidade atual em que scanningConfig.policy foi definido anteriormente como DISABLED:

A solicitação falha com um erro de violação de restrição da política da organização personalizada.

Para resolver esse problema, faça o seguinte:

  • Sua organização aplicou uma restrição de política da organização personalizada, como custom.skillsScanningEnforcement, em agentregistry.googleapis.com/Skill que nega resource.scanningConfig.policy == "DISABLED".
  • Se você estiver atualizando uma habilidade em que scanningConfig.policy foi definido como DISABLED antes da aplicação da política da organização, inclua uma atualização em scanningConfig.policy, definindo-o como ENABLED_BLOCKING ou um valor permitido, na solicitação UpdateSkill.
  • Para permitir a verificação desativada em ambientes de teste ou sandbox, peça ao administrador de políticas da organização para adicionar uma tag de isenção condicional, como exempt-scanning-enforcement: true, ao seu projeto.

Para mais informações, consulte Aplicar a verificação usando o serviço de políticas da organização.

A revisão de habilidade não foi verificada após a ativação da verificação

O erro a seguir vai ocorrer se você ativar a verificação em uma habilidade que já tem revisões enviadas:

O status da verificação (scanResult.scanState) de uma revisão atual permanece DISABLED, a revisão não é verificada e nenhuma descoberta de segurança é gerada.

A ativação da verificação de uma habilidade se aplica apenas às revisões de habilidades criadas após a ativação da verificação. O Agent Registry não verifica retroativamente as revisões criadas antes da ativação da verificação.

Para resolver esse problema, faça upload e registre uma nova revisão para a habilidade. Quando você faz upload da nova revisão, o Agent Registry verifica o payload de acordo com a configuração de verificação atualizada da habilidade. Para mais informações, consulte Criar uma revisão de habilidade e Verificar se há problemas de segurança nas habilidades.