Questa pagina mostra come risolvere i problemi relativi al registro degli agenti.
Quota di frequenza API superata
Potresti riscontrare questo problema se interagisci con l'API Agent Registry o se navighi rapidamente in Agent Registry nella console Google Cloud :
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.
Se si verifica la limitazione della velocità 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
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 AgentSpec e McpServerSpec
sono limitate a 10 kB. Comprimi i file JSON, rimuovi gli spazi vuoti
inutili 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 tue 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, verifica le impostazioni di Service Usage 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 molto tempo e sembra bloccata.
Per risolvere il problema, utilizza lo strumento get_operation MCP 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, il che può comportare tempi di operazione a lunga esecuzione (LRO) che potrebbero richiedere fino a 30 minuti. Configura le impostazioni di timeout del client
e interroga il 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 errore empty array o di accesso, anche se hai verificato l'esistenza del binding.
Per risolvere il problema, verifica che la tua entità disponga delle autorizzazioni
IAM (Identity and Access Management) 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 la
tua entità disponga dell'accesso richiesto al provider di autenticazione e del
ruolo roles/agentregistry.viewer nel progetto.