Risolvi i problemi relativi all'utilizzo di un agente con Agent Runtime

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 su "Vertex AI Reasoning Engine" 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-aiplatform

Soluzione consigliata:

Esegui questo comando nel terminale per aggiornare il pacchetto google-cloud-aiplatform:

pip install google-cloud-aiplatform --upgrade

Dopo 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-aiplatform

Se 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 Vertex AI

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 Vertex AI. Per utilizzare le estensioni di Vertex AI con Agent Runtime, concedi il ruolo Utente Vertex AI (roles/aiplatform.user) al account di servizio dell'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 IAM (Identity and Access Management) 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.

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 problema potrebbe essere dovuto a 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 motore di ragionamento corretto per il tuo agente.

Risorse di assistenza

Se il problema persiste, consulta la nostra guida di assistenza per ricevere aiuto.