Questo documento descrive come risolvere gli errori che potresti riscontrare durante l'utilizzo di un agente.
Nota: per cercare e filtrare i log degli errori dell'agente, utilizza Esplora log, seleziona RESOURCE TYPE in "Vertex AI Motore di ragionamento" e seleziona il valore RESOURCE CONTAINER corrispondente (ovvero il numero del progetto) e il valore REASONING ENGINE ID.
Gli schemi delle operazioni sono vuoti
Se l'agente restituisce un elenco vuoto da .operation_schemas(), il problema potrebbe essere causato da uno dei seguenti fattori:
Impossibile generare uno schema durante la creazione dell'agente
Problema:
Quando esegui il deployment dell'agente, ricevi un avviso simile al seguente:
WARNING:vertexai.agent_engines:failed to generate schema: issubclass() arg 1 must be a class
Possibile causa:
Questo avviso potrebbe essere visualizzato se esegui il deployment di un agente utilizzando il modello predefinito LangchainAgent su una versione di google-cloud-aiplatform precedente alla 1.49.0. Per verificare quale versione stai utilizzando, esegui questo comando nel terminale:
pip show google-cloud-aiplatformSoluzione consigliata:
Esegui questo comando nel terminale per aggiornare il pacchetto google-cloud-aiplatform:
pip install google-cloud-aiplatform --upgradeDopo aver aggiornato il pacchetto google-cloud-aiplatform, esegui questo comando per verificare che la versione sia 1.49.0 o successiva:
pip show google-cloud-aiplatformSe ti trovi in un'istanza di blocco note (ad esempio Jupyter, Colab o Workbench),
potresti dover riavviare il runtime per utilizzare il pacchetto aggiornato. Dopo aver verificato che la tua versione di google-cloud-aiplatform è 1.49.0 o successiva, prova a eseguire nuovamente il deployment dell'agente.
Errore PermissionDenied durante l'esecuzione di query sull'agente
La query potrebbe non riuscire se non disponi delle autorizzazioni richieste.
Autorizzazioni per le estensioni di Agent Platform
Problema
Potresti ricevere un errore PermissionDenied simile al seguente:
Permission 'aiplatform.extensions.get' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/extensions/
{EXTENSION}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
key: "permission"
value: "aiplatform.extensions.get"
}
metadata {
key: "resource"
value: "projects/{PROJECT_ID}/locations/{LOCATION}/extensions/{EXTENSION}"
}
]
Il tuo agente non dispone delle autorizzazioni per le estensioni di Agent Platform. Per utilizzare le estensioni di Agent Platform con Agent Runtime, concedi il ruolo Utente Agent Platform (roles/aiplatform.user) al account di servizio di identità dell'agente.
Per saperne di più, consulta Configura l'identità e le autorizzazioni per l'agente.
Autorizzazioni LLM
Problema:
Potresti ricevere un errore PermissionDenied simile al seguente:
PermissionDenied: 403 Permission 'aiplatform.endpoints.predict' denied on resource
'//aiplatform.googleapis.com/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/
google/models/{MODEL}' (or it may not exist). [reason: "IAM_PERMISSION_DENIED"
domain: "aiplatform.googleapis.com"
metadata {
key: "permission"
value: "aiplatform.endpoints.predict"
}
metadata {
key: "resource"
value: "projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL}"
}
]
Possibile causa:
Il service account dell'identità dell'agente potrebbe non disporre delle autorizzazioni appropriate per eseguire query sul modello linguistico di grandi dimensioni (LLM).
Soluzione consigliata:
Assicurati che il tuo account di servizio disponga delle autorizzazioni di Identity and Access Management (IAM) appropriate elencate nel messaggio di errore. Un esempio di autorizzazione IAM che potrebbe mancare è aiplatform.endpoints.predict. Per saperne di più, consulta Configura l'identità e le autorizzazioni per l'agente.
Richiesta rifiutata prima di raggiungere l'agente
Se la richiesta non va a buon fine prima che Agent Runtime la invii all'agente, la causa potrebbe essere uno dei seguenti problemi:
Agente non trovato
Problema:
La richiesta non va a buon fine con uno stato 404, NOT_FOUND (REASONING_ENGINE_NOT_FOUND) e un messaggio simile al seguente:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` was not found.
Possibili cause:
- L'ID progetto, località o risorsa nella richiesta non è corretto.
- L'agente è stato eliminato.
Soluzioni consigliate:
- Confronta il nome della risorsa nel messaggio di errore con gli agenti di cui hai eseguito il deployment. Consulta Elenco degli agenti di cui è stato eseguito il deployment.
- Assicurati che il client invii la richiesta al progetto e alla regione in cui hai eseguito il deployment dell'agente.
L'agente non è attivo
Problema:
La richiesta non va a buon fine con uno stato 403, PERMISSION_DENIED (REASONING_ENGINE_NOT_ACTIVE) e un messaggio simile al seguente:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` is not active, so it can't serve requests.
Possibili cause:
- L'agente è ancora in fase di creazione.
- Impossibile creare l'agente.
- L'agente è in fase di eliminazione.
Soluzioni consigliate:
- Se hai appena creato l'agente, attendi il completamento della creazione e poi riprova a inviare la richiesta.
- Se la creazione dell'agente non è riuscita, controlla i log collegati nel campo
logs_urldei metadati dell'errore per trovare la causa. Correggi l'errore ed esegui nuovamente il deployment dell'agente. Consulta Risolvi i problemi di deployment di un agente.
L'agente non ha istanze in esecuzione
Problema:
La richiesta non va a buon fine con uno stato 400, FAILED_PRECONDITION (REASONING_ENGINE_NO_RUNNING_INSTANCES) e un messaggio simile al seguente:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` has no running instances because no agent is deployed to it.
Possibile causa:
La risorsa esiste, ma non è stato specificato alcun agente (oggetto, file di origine o immagine container) per il deployment durante la creazione o l'aggiornamento.
Soluzione consigliata:
Aggiorna la risorsa con un agente di cui eseguire il deployment. Consulta Aggiorna un agente di cui è stato eseguito il deployment.
Metodi A2A non definiti
Problema:
Una richiesta A2A non va a buon fine con uno stato 400, FAILED_PRECONDITION (REASONING_ENGINE_A2A_NOT_CONFIGURED) e un messaggio simile al seguente:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` does not define A2A methods, so it can't serve A2A requests.
Possibile causa:
Hai inviato una richiesta A2A, ad esempio una richiesta per la scheda dell'agente o un messaggio, a un agente che non è stato creato come agente A2A.
Soluzioni consigliate:
- Per gestire le richieste A2A, esegui il deployment di un agente A2A. Consulta Crea un agente A2A.
- Per eseguire una query su un agente che non è un agente A2A, consulta Utilizza un agente.
Il payload della richiesta è troppo grande
Problema:
La richiesta non va a buon fine con uno stato 400, FAILED_PRECONDITION
(REASONING_ENGINE_REQUEST_TOO_LARGE) o un errore HTTP 413 Request Entity Too Large
e un messaggio simile al seguente:
The request to the Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` exceeds the 32 MiB maximum HTTP payload size (about 24 MiB for Base64-encoded files).
Possibili cause:
- Agent Runtime applica una dimensione massima fissa del corpo della richiesta HTTP di 32 MiB.
- Gli allegati dei file incorporati con codifica Base64 in JSON si espandono di circa il 33%, quindi i file di dimensioni superiori a circa 24 MiB superano il limite di payload di 32 MiB.
- Nelle conversazioni a più turni, la cronologia delle conversazioni accumulata e gli allegati precedenti inviati nel payload della richiesta fanno sì che il corpo della richiesta superi i 32 MiB.
Soluzioni consigliate:
- Carica file di grandi dimensioni su Cloud Storage e passa gli URI
gs://nella tua richiesta anziché i byte codificati in Base64 in linea. - Comprimi, suddividi o riduci gli allegati di grandi dimensioni prima di inviarli, in modo che il corpo della richiesta HTTP serializzata totale rimanga inferiore a 32 MiB (circa 24 MiB di file non elaborati).
- Inizia una nuova conversazione o rimuovi gli allegati precedenti dalla cronologia delle conversazioni quando il contesto a più turni si avvicina al limite.
Esecuzione del motore di ragionamento non riuscita
Se ricevi il messaggio di errore "Esecuzione del motore di ragionamento non riuscita" quando esegui una query sull'agente, il motivo potrebbe essere uno dei problemi descritti in questa sezione.
Input non validi per .query()
Problema:
Potresti ricevere un errore FailedPrecondition simile al seguente:
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"Invalid request: `{'query': ...}`"}
Possibile causa:
Questo errore si verifica quando specifichi gli input della query come argomenti posizionali anziché come argomenti di parole chiave. Ad esempio, chiami agent.query(query_str) anziché agent.query(input=query_str).
Soluzione consigliata:
Quando esegui una query su un'istanza di un motore di ragionamento di cui è stato eseguito il deployment, specifica tutti gli input come argomenti delle parole chiave.
Quota del modello Gemini esaurita
Problema:
Potresti ricevere un errore simile a uno dei seguenti, che indica che l'errore è stato generato dalla chiamata a Gemini:
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.ResourceExhausted: 429 Unable to submit request because the service is temporarily out of capacity. Try again later."}
oppure un messaggio di errore diverso:
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.InternalServerError: 500 Internal error occurred."}
Possibile causa:
Questo potrebbe accadere se di recente hai inviato troppe richieste e hai esaurito la quota del modello Gemini.
Soluzione consigliata:
Segui la procedura di gestione della quota del modello Gemini per aumentare la quota. In alternativa, limita la frequenza dei test e riprova più tardi.
ID motore di ragionamento errato
Problema:
Potresti ricevere un errore che indica che l'esecuzione del motore di ragionamento non è riuscita con un dettaglio di Not Found.
Possibile causa:
Questo errore può verificarsi se utilizzi un ID motore di ragionamento errato quando esegui una query sull'agente.
Soluzione consigliata:
Verifica di utilizzare l'ID del motore di ragionamento corretto per l'agente.
Risorse di assistenza
Se il problema persiste, consulta la nostra guida di assistenza per ricevere aiuto.