Risolvere i problemi del registro degli agenti

Quando registri, scopri o connetti i componenti in Agent Registry, puoi diagnosticare e risolvere problemi comuni come limiti di quota, errori di convalida del payload e delle skill, mancate corrispondenze della località, ritardi di sincronizzazione ed errori di autorizzazione.

Quota di frequenza API superata

Il seguente errore si verifica se superi il limite di tasso di richieste quando interagisci con l'API Agent Registry o navighi rapidamente in Agent Registry nella consoleGoogle Cloud :

429 Too Many Requests

Per risolvere il problema, implementa il backoff esponenziale nei client API per gestire i tassi di richieste. L'API Agent Registry ha una quota di frequenza predefinita di 1200 richieste al minuto o 20 query al secondo, a livello globale e per regione.

Se riscontri una limitazione quando cambi scheda nella console Google Cloud , attendi qualche istante e riprova. Se il tuo caso d'uso programmatico richiede limiti più elevati, richiedi un aumento della quota per la metrica RequestsPerMinute.

Errore relativo alle dimensioni del payload durante la registrazione manuale

Il seguente errore si verifica quando registri manualmente un agente o un server MCP con un file di specifica che supera il limite di dimensioni:

L'API rifiuta la richiesta con un errore che indica che il payload è troppo grande.

Per risolvere il problema, verifica che il file agent-card.json o toolspec.json sia inferiore a 10 KB. Le dimensioni dei contenuti AgentSpec e McpServerSpec sono limitate a 10 kB. Minimizza i file JSON, rimuovi gli spazi vuoti non necessari o condensa le descrizioni degli strumenti per rispettare questo limite. Per saperne di più, consulta Schemi JSON.

Agenti o server MCP mancanti dopo la creazione

Il seguente errore si verifica dopo aver creato un agente o un server MCP in un prodotto Google Cloud supportato, ad esempio Google Workspace o Gemini Enterprise:

La risorsa non viene visualizzata nell'output quando chiami le API ListAgents o ListMcpServers.

Per risolvere il problema, attendi il completamento della sincronizzazione in background. Le tue risorse vengono aggiornate in tempo reale, ma i job batch offline periodici compilano altre integrazioni. Se la risorsa non viene visualizzata dopo diverse ore, verifica le impostazioni di Utilizzo dei servizi del progetto e assicurati che l'API pertinente sia abilitata.

Le operazioni a lunga esecuzione sembrano bloccate

Il seguente errore si verifica quando esegui il deployment degli agenti o configuri associazioni complesse:

L'operazione richiede molto tempo e sembra bloccata.

Per risolvere il problema, utilizza lo strumento MCP get_operation o l'endpoint API google.longrunning.Operations.GetOperation per eseguire il polling dello stato dell'operazione. Alcune creazioni di backend di agenti e MCP richiedono un provisioning significativo dell'infrastruttura, il che può comportare tempi di operazione a lunga esecuzione (LRO) che possono richiedere fino a 30 minuti. Configura le impostazioni di timeout del client di conseguenza ed esegui il polling del flag booleano done per verificare il completamento.

Risultati vuoti durante il recupero delle associazioni disponibili

Se recuperi le associazioni disponibili per un provider di autenticazione senza autorizzazioni sufficienti per la risorsa AuthProvider di destinazione, si verifica il seguente errore:

L'API restituisce un array vuoto o un errore di accesso, anche se l'associazione esiste.

Per risolvere il problema, verifica che l'entità disponga delle autorizzazioni Identity and Access Management (IAM) corrette per la risorsa AuthProvider di destinazione. L'API applica controlli IAM rigorosi e rimuove gli oggetti Binding che fanno riferimento a provider di autenticazione a cui il chiamante non ha accesso. Assicurati che l'entità disponga dell'accesso richiesto al provider di autenticazione e del ruolo roles/agentregistry.viewer nel progetto.

Il download della revisione della skill non riesce con l'errore 302

Il seguente errore si verifica se tenti di scaricare un payload di revisione delle competenze utilizzando l'API GetSkillRevision con il parametro di query ?alt=media e il tuo client HTTP non segue i reindirizzamenti:

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

Per risolvere il problema, verifica che il client HTTP sia configurato per seguire automaticamente i reindirizzamenti. L'endpoint ?alt=media richiede un reindirizzamento 302 per scaricare correttamente l'archivio della skill. Ad esempio, se utilizzi curl, aggiungi il flag -L o --location al comando.

La convalida della revisione della skill non va a buon fine o mostra lo stato FAILED

Il seguente errore si verifica quando crei una nuova revisione della skill con un file ZIP non valido:

La revisione passa allo stato FAILED e non può essere caricata dagli agenti.

Per risolvere il problema, controlla i log di convalida o esamina i contenuti del payload ZIP:

• Assicurati che il file ZIP contenga un file SKILL.md nella directory radice.
• Verifica che il file SKILL.md abbia un blocco front matter YAML valido con name e description definiti.
• Verifica che il payload ZIP non superi i limiti di dimensione: la dimensione compressa deve essere inferiore a 500 KB, la dimensione totale non compressa inferiore a 10 MB e la dimensione del singolo file inferiore a 1 MB.
• Verifica che l'archivio non contenga link simbolici, elementi di attraversamento delle directory come .. o percorsi assoluti.

Le skill autonome non vengono visualizzate negli elenchi di risorse di servizi o agenti

Il seguente errore si verifica se esegui una query sugli elenchi di agenti o servizi per le skill autonome, ad esempio eseguendo gcloud agent-registry services list o gcloud agent-registry agents list:

La competenza autonoma non viene visualizzata nell'output.

Per risolvere il problema, esegui invece una query sulla raccolta skills:

• A differenza degli agenti, dei server MCP e degli endpoint registrati manualmente, le skill autonome non utilizzano risorse Service scrivibili o risorse di rilevamento Agent, McpServer o Endpoint. Invece, Agent Registry rappresenta le skill autonome direttamente come risorse Skill di primo livello e risorse SkillRevision con controllo delle versioni.
• Per elencare, cercare o ispezionare le skill autonome, utilizza la scheda Skill nella consoleGoogle Cloud , esegui gcloud alpha agent-registry skills list o gcloud alpha agent-registry skills search oppure chiama i metodi dell'API REST skills. Per istruzioni, vedi Gestisci le skill e Cerca skill autonome.
• Se stai cercando skill A2A in linea dichiarate nella scheda di un agente, controlla il campo skills nella risorsa di rilevamento Agent utilizzando gcloud agent-registry agents describe o gcloud agent-registry agents search.

Errore di entità risorsa non trovata durante la gestione delle policy IAP

Il seguente errore si verifica quando utilizzi i comandi gcloud iap web per gestire le policy in uscita di Identity-Aware Proxy (IAP) sulle risorse di Agent Registry:

NOT_FOUND: Requested entity was not found

Per risolvere il problema, verifica quanto segue:

• Stato della registrazione: verifica che il componente di destinazione sia registrato in Agent Registry nella posizione prevista.
• Formato dell'identificatore: verifica che il comando o l'associazione della policy specifichi il nome della risorsa standard anziché un URN dell'identificatore del registry.
• Flag della risorsa: verifica che il flag della risorsa che passi a gcloud iap web corrisponda al tipo di risorsa secondaria Agent Registry sottostante:
  • Per gli endpoint, ad esempio le API esterne o i punti di uscita delle API di Google, utilizza il flag --endpoint.
  • Per i server Model Context Protocol, utilizza il flag --mcp-server.
  • Per gli agenti registrati, utilizza il flag --agent.

Controlla il nome della risorsa restituito da gcloud agent-registry endpoints list, gcloud agent-registry mcp-servers list o gcloud agent-registry agents list per verificare se il nome della risorsa contiene /endpoints/, /mcpServers/ o /agents/. Se passi il flag della risorsa sbagliato, ad esempio --endpoint per un ID server MCP, viene generato un errore NOT_FOUND.

Autorizzazione negata durante l'applicazione delle policy IAM web IAP

Il seguente errore si verifica quando applichi o modifichi le policy IAM web di IAP per le risorse del registro degli agenti senza i ruoli amministrativi richiesti:

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

Per risolvere il problema, verifica che l'utente o il account di servizio attivo disponga delle autorizzazioni richieste per il progetto che ospita il registry e il gateway:

• Assicurati che il chiamante disponga del ruolo Amministratore policy IAP (roles/iap.admin) o Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) nel progetto di governance centrale.
• Verifica che il chiamante disponga delle autorizzazioni iap.web.setIamPolicy e resourcemanager.projects.setIamPolicy.

Server MCP remoto non trovato in una località regionale

Il seguente errore si verifica se esegui una query per un server MCP Google o Google Cloud remoto registrato automaticamente o se applichi una policy in uscita di IAP in una località regionale come us-central1:

La richiesta restituisce un errore NOT_FOUND o un elenco vuoto, anche se il servizio fornisce endpoint regionali (REP) o se il traffico viene instradato tramite un Agent Gateway regionale.

Quando Agent Registry registra automaticamente un server MCP Google o Google Cloud remoto per un'API abilitata, crea la McpServer risorsa solo nella località global, non in singole regioni come us-central1. Se il servizio fornisce endpoint regionali, ad esempio https://SERVICE.REGION.rep.googleapis.com/mcp, Agent Registry elenca questi URL regionali nel campo interfaces di quella singola risorsa global McpServer.

Per risolvere questo problema, procedi in uno dei seguenti modi:

• Utilizza global per i server registrati automaticamente: specifica la località global quando esegui query sul server in Agent Registry con --location=global o applica policy in uscita IAP con --region=global, anche quando l'agente chiamante instrada il traffico tramite un gateway regionale.
• Registrati in una regione per la residenza dei dati: se devi conservare i metadati del registry in una regione specifica, esegui il deployment dei server MCP personalizzati nei runtime Cloud Run o Google Kubernetes Engine (GKE) regionali oppure registra manualmente il server MCP e l'URL dell'endpoint regionale in quella regione, quindi applica la policy IAP nella stessa regione. Quando Agent Gateway risolve un URL di destinazione, le voci del registry regionale hanno la precedenza sulle voci global.

Errori di mancata corrispondenza della regione durante la configurazione di Model Armor su Agent Gateway

Il seguente errore si verifica quando configuri i filtri delle policy di Model Armor su Agent Gateway in regioni non corrispondenti:

La creazione della policy di autorizzazione non va a buon fine con un errore di mancata corrispondenza della regione oppure il traffico instradato tramite il gateway a un server MCP non supera la valutazione della policy.

Per risolvere il problema, verifica l'allineamento regionale delle risorse del gateway e delle associazioni delle policy di destinazione:

• Allinea le regioni di Agent Gateway e Model Armor: assicurati che Agent Gateway, i template di Model Armor, l'estensione dell'autorizzazione e la policy si trovino tutti nella stessa regione, ad esempio us-central1.
• Instradamento ai server MCP global o regionali: non è necessario registrare nuovamente i server MCP global in una regione solo per utilizzare Model Armor. Poiché Model Armor ispeziona i payload di richiesta e risposta nel gateway regionale, un gateway regionale può ispezionare e gestire il traffico indirizzato ai server MCP registrati nella località global e alle destinazioni regionali.
• Abbina le associazioni in uscita IAP alla località di registrazione della destinazione: applica l'associazione di autorizzazione in uscita IAP nella località in cui è registrata la risorsa McpServer di destinazione. Utilizza global per i server MCP remoti registrati automaticamente o utilizza la regione specifica per i server MCP registrati a livello di regione.

La registrazione manuale o la creazione dell'associazione non riesce in una località multiregionale

Il seguente errore si verifica se tenti di registrare manualmente un agente, un server MCP o un endpoint o di creare un binding in una località multiregionale come us o eu:

L'API rifiuta la richiesta con un errore di località non supportata o argomento non valido.

Per risolvere il problema, specifica una località regionale supportata, ad esempio us-central1 o europe-west1, oppure la località global. Le località multiregionali us e eu supportano solo il rilevamento di componenti registrati automaticamente e la registrazione o il rilevamento di skill autonome. Per l'elenco delle località supportate, consulta Località di Agent Registry.

Errori durante l'accesso ad Agent Registry con la federazione delle identità per la forza lavoro

I seguenti errori si verificano se accedi al registro degli agenti nella consoleGoogle Cloud o utilizzi Google Cloud CLI dopo l'autenticazione con la federazione delle identità per la forza lavoro:

La consoleGoogle Cloud mostra errori di caricamento generici, come i seguenti:

• "Si è verificato un errore durante il caricamento…"
• "Il server non è riuscito a completare la tua richiesta"
• "Impossibile caricare"

Inoltre, i comandi gcloud potrebbero restituire un errore interno, ad esempio error 13: an internal error has occurred.

Per risolvere il problema, esegui l'autenticazione con un Account Google standard gestito tramite Cloud Identity o Google Workspace. Assicurati che l'account disponga delle autorizzazioni richieste, ad esempio roles/agentregistry.admin o roles/agentregistry.viewer.

I servizi di governance di Gemini Enterprise Agent Platform hanno un supporto limitato per le identità federate. La concessione di ruoli IAM più ampi a un'entità federata non risolve il problema.