Risolvere i problemi del registro degli agenti

Questa pagina mostra come risolvere i problemi relativi ad Agent Registry.

Quota di frequenza API superata

Potresti riscontrare questo problema se interagisci con l'API Agent Registry o navighi rapidamente in Agent Registry in Google Cloud console:

429 Too Many Requests

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

Se riscontri limitazioni quando passi da una scheda all'altra in Google Cloud console, 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 di dimensioni del payload durante la registrazione manuale

Potresti riscontrare questo problema se registri manualmente un agente o un server MCP: 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 di AgentSpec e McpServerSpec sono limitate a 10 KB. Riduci al minimo 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

Potresti riscontrare questo problema se crei un agente o un server MCP in un prodotto Google Cloud supportato, come Google Workspace o Gemini Enterprise: la risorsa non viene visualizzata quando chiami le API ListAgents o ListMcpServers.

Per risolvere il problema, attendi il completamento della sincronizzazione in background. Le risorse vengono aggiornate in tempo reale, ma altre integrazioni vengono compilate da job batch offline eseguiti periodicamente. Se la risorsa non viene visualizzata dopo diverse ore, controlla le impostazioni di utilizzo del servizio del progetto e assicurati che l'API pertinente sia abilitata.

Le operazioni a lunga esecuzione sembrano bloccate

Potresti riscontrare questo problema se esegui il deployment di agenti o configuri binding complessi: l'operazione richiede una quantità di tempo significativa 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 dell'infrastruttura significativo, che può comportare tempi di esecuzione di operazione a lunga esecuzione (LRO) che potrebbero richiedere fino a 30 minuti. Di conseguenza, configura le impostazioni di timeout del client ed esegui il polling del flag booleano done per verificare il completamento.

Risultati vuoti durante il recupero dei binding disponibili

Potresti riscontrare questo problema se recuperi i binding disponibili per un provider di autenticazione: l'API restituisce un empty array o un errore di accesso, anche se hai verificato che il binding esiste.

Per risolvere il problema, verifica che la principale disponga delle autorizzazioni di Identity and Access Management (IAM) corrette sulla 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 la principale 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

Potresti riscontrare questo problema se provi a scaricare un payload di revisione della skill utilizzando l'API GetSkillRevision con il parametro di query ?alt=media: la richiesta non riesce e restituisce un errore simile al seguente:

{
  "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 riesce o mostra lo stato FAILED

Potresti riscontrare questo problema dopo aver creato una nuova revisione della skill: la revisione passa allo stato FAILED e non può essere caricata dagli agenti.

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

  • Assicurati che l'archivio ZIP contenga un file SKILL.md nella sua radice.
  • Verifica che il file SKILL.md abbia un blocco frontmatter YAML valido con name e description definiti.
  • Verifica che il payload ZIP non superi i limiti di dimensioni: le dimensioni compresse devono essere inferiori a 500 KB, le dimensioni totali non compresse inferiori a 10 MB e le dimensioni dei singoli file inferiori a 1 MB.
  • Verifica che l'archivio non contenga link simbolici, elementi di attraversamento della directory come .. o percorsi assoluti.