Risolvere i problemi relativi al deployment di un agente

Questo documento descrive come risolvere gli errori che potresti riscontrare durante il deployment di un agente in Agent Runtime. Copre una serie di problemi comuni, tra cui errori di serializzazione, errori di autorizzazione e violazioni del perimetro dei Controlli di servizio VPC.

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.

Errori di build e avvio del container

Se il deployment non va a buon fine durante la creazione o l'avvio del container dell'agente da parte di Agent Runtime, la causa potrebbe essere uno dei seguenti problemi:

Creazione dell'immagine container non riuscita

Problema:

Il deployment non riesce con uno stato 400, INVALID_ARGUMENT (REASONING_ENGINE_BUILD_FAILED) e un messaggio simile al seguente:

The Reasoning Engine could not be deployed because its container image failed to build.

Possibili cause:

Quando esegui il deployment di un agente da un oggetto agente, da file di origine o da un Dockerfile, Agent Runtime crea un'immagine container per l'agente. La build non va a buon fine se uno dei seguenti passaggi non riesce:

  • Installazione dei requisiti del pacchetto: un pacchetto in requirements o il file dei requisiti dei file di origine non esiste, blocca una versione che non esiste, è in conflitto con un altro pacchetto o non supporta la versione Python dell'agente.
  • Installazione di un file wheel locale: un file wheel elencato in requirements non è incluso anche in extra_packages, pertanto non è disponibile per l'installazione.
  • Esecuzione degli script di installazione: uno script nella directory installation_scripts esce con un errore.
  • Creazione del Dockerfile: quando esegui il deployment da un Dockerfile (image_spec), un'istruzione nel Dockerfile non va a buon fine.

Soluzioni consigliate:

  • Controlla i log di build collegati nel campo logs_url dei metadati dell'errore per trovare il passaggio che non è riuscito. Le voci dei log di build includono l'ID log reasoning_engine_build. Per eseguire query sui log, consulta Creazione di query.
  • Per riprodurre l'errore localmente, installa gli stessi requisiti in un nuovo ambiente virtuale che utilizza la versione Python dell'agente di cui è stato eseguito il deployment e correggi eventuali errori segnalati da pip:

    python -m venv agent-env
    agent-env/bin/pip install -r requirements.txt
  • Per fare in modo che la build installi le versioni che hai testato localmente, blocca le versioni dei pacchetti. Consulta Definisci i requisiti del pacchetto.

  • Se installi un wheel locale, includilo sia in requirements che in extra_packages. Consulta Definisci pacchetti aggiuntivi.

  • Se utilizzi script di installazione, assicurati che ogni script venga eseguito correttamente con autorizzazioni root in un ambiente pulito. Consulta Definisci le opzioni di build.

  • Se esegui il deployment da un Dockerfile, crea l'immagine container localmente dagli stessi file di origine (ad esempio con docker build) e correggi eventuali istruzioni che non vanno a buon fine.

Soluzioni non applicabili:

  • Se riprovi a eseguire il deployment senza modificare i requisiti, gli script di installazione o il Dockerfile, l'errore si ripete perché la build esegue gli stessi passaggi.

Timeout della build dell'immagine container

Problema:

Il deployment non riesce con uno stato 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) e un messaggio che indica che la creazione dell'immagine container dell'agente non è stata completata in tempo.

Possibili cause:

Quando esegui il deployment dai file di origine, Agent Runtime crea un'immagine container che installa il codice e le relative dipendenze. Il deployment non va a buon fine se la build è ancora in esecuzione quando scade il tempo consentito. In genere, le build richiedono troppo tempo a causa delle dipendenze che installano, ad esempio:

  • Un lungo elenco di pacchetti in requirements, inclusi quelli non utilizzati dall'agente.
  • Pacchetti senza wheel predefinite per l'ambiente di build, che vengono compilati dall'origine durante la build.
  • Versioni non bloccate o bloccate in modo approssimativo, che rallentano la risoluzione delle dipendenze.

Soluzioni consigliate:

  • Controlla i log di build collegati nel campo logs_url dei metadati di errore per vedere quale passaggio era in esecuzione quando la build è stata interrotta.
  • Rimuovi le dipendenze non necessarie e blocca le versioni di tutti i pacchetti richiesti.
  • Dai la priorità ai pacchetti e alle versioni che pubblicano wheel predefinite, in modo che non venga compilato nulla durante la build.
  • Riprova a eseguire il deployment. A volte una build può richiedere più tempo del solito per motivi non correlati al tuo codice.

Impossibile avviare il container

Problema:

Il deployment non riesce con uno stato 400, INVALID_ARGUMENT (REASONING_ENGINE_CONTAINER_FAILED_TO_START) e un messaggio che indica che il container dell'agente non ha iniziato la pubblicazione entro il timeout di avvio.

Possibili cause:

Agent Runtime avvia l'agente in un container e attende che accetti le richieste. Il deployment non riesce se il container si chiude o non risponde prima del timeout di avvio. Le cause più comuni possono essere le seguenti:

  • Dipendenza mancante: l'agente importa un pacchetto che non è elencato in requirements o extra_packages, pertanto il caricamento dell'agente non va a buon fine e viene visualizzato un errore come ModuleNotFoundError.
  • Mancata corrispondenza della versione del pacchetto: i pacchetti installati nell'ambiente di cui è stato eseguito il deployment sono diversi da quelli nell'ambiente di sviluppo, pertanto il caricamento dell'agente non va a buon fine e viene visualizzato un errore come AttributeError: Can't get attribute. Consulta la sezione Errori di serializzazione.
  • Errore durante l'inizializzazione: il metodo set_up() dell'agente o un altro codice eseguito durante il caricamento dell'agente genera un'eccezione o attende una risorsa che non può raggiungere.
  • Inizializzazione lenta: il caricamento dell'agente richiede più tempo del timeout di avvio.
  • Container personalizzato non in ascolto: un container personalizzato deve rimanere in ascolto delle richieste HTTP su 0.0.0.0 sulla porta 8080. Consulta il contratto di runtime.
  • Agent Gateway blocca l'avvio: quando instradi il traffico tramite Agent Gateway, l'avvio non va a buon fine se Identity-Aware Proxy (IAP) blocca le chiamate di inizializzazione, se l'identità dell'agente non dispone dei ruoli richiesti o se un container personalizzato non considera attendibile il certificato radice del gateway. Consulta Errori durante l'avvio di Agent Runtime e L'agente di cui è stato eseguito il deployment con un container personalizzato (BYOC) non riesce a connettersi ad Agent Gateway.

Soluzioni consigliate:

  • Controlla i log dell'agente collegati nel campo logs_url dei metadati dell'errore per trovare l'errore che ha arrestato il container. Consulta Visualizza i log di un agente.
  • Aggiungi eventuali pacchetti mancanti a requirements o extra_packages e blocca le versioni che utilizzi in fase di sviluppo.
  • Per riprodurre l'errore localmente, installa solo i pacchetti elencati in requirements in un ambiente pulito con la stessa versione di Python, quindi importa e crea un'istanza dell'agente.
  • Sposta le operazioni lente o soggette a errori, come la connessione a servizi esterni, fuori dall'inizializzazione dell'agente.
  • Per un container personalizzato, assicurati che il server sia in ascolto su 0.0.0.0 e sulla porta nella variabile di ambiente PORT (valore predefinito 8080).

Soluzioni non applicabili:

  • Se riprovi a eseguire il deployment senza modificare l'agente o le sue dipendenze, di solito l'operazione non va a buon fine per lo stesso motivo, perché la causa risiede nel codice dell'agente o nel suo ambiente.

Il container non è stato avviato in tempo

Problema:

Il deployment non riesce con uno stato 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) e un messaggio che indica che il container dell'agente non ha iniziato la pubblicazione in tempo.

Possibili cause:

Dopo la creazione dell'immagine, Agent Runtime avvia il container dell'agente e attende che sia pronto per gestire le richieste. Il deployment non va a buon fine se il container è ancora in fase di avvio quando il tempo consentito si esaurisce. Le cause più comuni possono includere:

  • Lavoro lento al momento dell'importazione, ad esempio il caricamento di modelli o file di grandi dimensioni quando vengono importati i moduli dell'agente.
  • Lavoro lento o bloccante nel metodo set_up() dell'agente, ad esempio chiamate di rete che attendono un servizio non raggiungibile.

Soluzioni consigliate:

  • Controlla i log del container collegati nel campo logs_url dei metadati di errore per vedere dove si è bloccato l'avvio.
  • Sposta l'inizializzazione costosa fuori dal tempo di importazione del modulo e riduci al minimo il numero di passaggi in set_up() fast. Rimanda il lavoro non necessario per gestire la prima richiesta.
  • Assicurati che tutti i servizi chiamati dall'agente durante l'avvio siano raggiungibili dall'agente e imposta i timeout su queste chiamate in modo che non possano bloccare l'avvio a tempo indeterminato.
  • Se i log del container mostrano che l'agente è stato avviato normalmente, riprova il deployment. A volte l'avvio può richiedere più tempo del solito per motivi non correlati al tuo codice.

Errori dei modelli predefiniti

Se riscontri problemi con il template LangchainAgent durante il deployment, il motivo potrebbe essere uno dei problemi descritti in questa sezione.

Errori interni del server

Problema:

Ricevi un messaggio di errore simile al seguente:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Purtroppo, si tratta di un errore generico per qualsiasi problema con il container in fase di runtime e la possibile causa è uno dei tanti errori che potrebbero verificarsi.

Possibili cause:

  • Stato non aggiornato su LangchainAgent. Questo potrebbe accadere se .set_up() è stato chiamato su un LangchainAgent prima di eseguire il deployment dell'agente.
  • Versioni dei pacchetti incoerenti. Questo può accadere se i pacchetti installati nell'ambiente di sviluppo sono diversi da quelli installati nell'ambiente remoto in Agent Runtime.

Soluzioni consigliate:

Errori di serializzazione

In generale, è importante assicurarsi che gli ambienti "locale" e "remoto" siano sincronizzati durante il deployment dell'agente. Puoi assicurarti che ciò avvenga specificando requirements= quando esegui il deployment dell'agente.

Se riscontri problemi con la serializzazione (gli errori relativi a "pickle" o "pickling" sono sinonimi di errori di "serializzazione"), il motivo potrebbe essere uno dei problemi descritti in questa sezione.

Versione Pydantic

Problema:

Ricevi un messaggio di errore simile al seguente:

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

Possibile causa:

Questo potrebbe accadere se il tuo pacchetto pydantic è precedente alla versione 2.6.4. Per verificare la versione in uso, esegui questo comando nel terminale:

pip show pydantic

Soluzione consigliata:

Aggiorna il pacchetto eseguendo questo comando nel terminale:

pip install pydantic --upgrade

Esegui questo comando nel terminale per verificare che stai utilizzando la versione 2.6.4 o una versione successiva:

pip show pydantic

Se ti trovi in un'istanza di blocco note (ad esempio Jupyter, Colab o Workbench), potresti dover riavviare il runtime per utilizzare i pacchetti aggiornati.

Versione Cloudpickle

Problema:

Ricevi un messaggio di errore simile al seguente:

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

Possibile causa:

Questo può accadere se la versione del pacchetto cloudpickle è diversa nell'ambiente di sviluppo e nell'ambiente di deployment. Per verificare quale versione stai utilizzando in fase di sviluppo, esegui questo comando nel terminale:

pip show cloudpickle

Soluzione consigliata:

Esegui il deployment della stessa versione di cloudpickle in entrambi gli ambienti, ad esempio l'ambiente di sviluppo locale e l'agente di cui è stato eseguito il deployment remoto, specificando requirements= quando esegui il deployment dell'agente.

Errori interni del server

Problema:

Ricevi un messaggio di errore simile al seguente:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Possibile causa:

Questo può accadere se sys_version= è diverso dall'ambiente di sviluppo durante il deployment dell'agente.

Soluzione consigliata:

Dopo aver eseguito il deployment dell'agente, valuta la possibilità di rimuovere sys_version= dagli argomenti di input. Se i problemi persistono, invia una segnalazione di bug.

Errori del bucket Cloud Storage

Se riscontri problemi con il bucket di gestione temporanea di Cloud Storage utilizzato al momento del deployment per raccogliere e caricare l'agente, il motivo potrebbe essere uno dei seguenti:

Errori di autorizzazione

Soluzione consigliata:

Se vuoi utilizzare un bucket preesistente: assicurati che l'entità autenticata per utilizzare Agent Platform (tu o un account di servizio) abbia accesso Storage Admin al bucket e concedi le autorizzazioni al service account.

In alternativa, puoi specificare un nuovo bucket durante il deployment dell'agente e l'SDK creerà il bucket con le autorizzazioni necessarie.

Se i problemi persistono, invia una segnalazione di bug.

La sottodirectory del bucket Cloud Storage non viene creata

Problema:

Ricevi un messaggio di errore simile al seguente:

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

(L'errore 404 si verifica quando il sistema tenta di copiare in una cartella che non esiste).

Possibile causa:

Questo è probabilmente dovuto a un problema con l'interpolazione di stringhe nelle versioni di google-cloud-aiplatform precedenti alla versione 1.49.0. Questo problema è stato risolto nelle versioni successive. Per verificare quale versione di google-cloud-aiplatform stai utilizzando, esegui questo comando nel terminale:

pip show google-cloud-aiplatform

Soluzione consigliata:

Aggiorna il pacchetto eseguendo questo comando nel terminale:

pip install google-cloud-aiplatform --upgrade

Verifica di utilizzare la versione 1.49.0 o una versione successiva di google-cloud-aiplatform eseguendo questo comando nel terminale:

pip show google-cloud-aiplatform

Se utilizzi un'istanza di blocco note (ad esempio Jupyter, Colab o Workbench), potresti dover riavviare il runtime prima di poter utilizzare i pacchetti aggiornati.

Errori di violazione VPC-SC

Se riscontri problemi con i Controlli di servizio VPC, la causa potrebbe essere uno dei seguenti problemi:

Errori di autorizzazione

Problema:

Ricevi un messaggio di errore simile al seguente:

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

oppure:

Request is prohibited by organization's policy.

Possibile causa:

Ciò è probabilmente dovuto alla mancanza delle regole in entrata richieste nel perimetro VPC-SC.

Soluzione consigliata:

Se utilizzi Agent Platform in un ambiente VPC-SC, devi creare una regola in entrata nel perimetro per consentire l'accesso dall'agente di servizio del motore di ragionamento (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) al servizio storage.googleapis.com e al servizio artifactregistry.googleapis.com.

Errori del account di servizio personalizzato

Se riscontri problemi con i service account, la causa potrebbe essere uno dei seguenti problemi:

Agisci come account di servizio

Problema:

Ricevi un messaggio di errore simile al seguente:

You do not have permission to act as service_account.

Possibile causa:

Potresti non disporre dell'autorizzazione iam.serviceAccounts.actAs sul account di servizio personalizzato utilizzato per il deployment. Tieni presente che in un sistema multi-agente in cui sono presenti più service account personalizzati, un autore o un deployer di agenti può agire come alcuni dei service account. Se utilizzi l'account di servizio sbagliato, questo errore è il comportamento previsto.

Inoltre, potresti riscontrare questo errore se il account di servizio personalizzato si trova in un progetto diverso da quello in cui esegui il deployment dell'agente e la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage viene applicata nel progetto del account di servizio.

Consulta Service account personalizzato tra progetti per l'elenco completo delle configurazioni richieste per questo scenario.

Soluzione consigliata:

Assicurati di utilizzare il account di servizio previsto. Controlla se disponi del ruolo Utente account di servizio (roles/iam.serviceAccountUser) per questo service account. In caso contrario, chiedi all'amministratore di concederti il ruolo per questo service account.

Se ti trovi nello scenario tra progetti, verifica se nel progetto del account di servizio è applicata la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. In questo caso, chiedi all'amministratore di disattivare la policy.

Server dei metadati non disponibile

Problema:

Ricevi un messaggio di errore simile al seguente:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

o

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

Possibile causa:

Questo può accadere se il account di servizio personalizzato e l'agente si trovano in progetti diversi e l'agente di servizio AI Platform Reasoning Engine non dispone dell'autorizzazione iam.serviceAccounts.getAccessToken sul account di servizio personalizzato.

Consulta Service account personalizzato tra progetti per l'elenco completo delle configurazioni richieste per questo scenario.

Soluzione consigliata:

Chiedi all'amministratore di concedere all'agente di servizio AI Platform Reasoning Engine del progetto dell'agente il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) nell'account di servizio personalizzato.

L'agente di servizio AI Platform Reasoning Engine deve trovarsi nello stesso progetto che utilizzi per eseguire il deployment dell'agente. L'associazione IAM della concessione del ruolo deve trovarsi nel progetto in cui risiede il service account personalizzato.

Provisioning dell'ambiente non riuscito

Problema:

La creazione di un agente non va a buon fine con uno stato 500, INTERNAL (REASONING_ENGINE_PROVISIONING_FAILED) e un messaggio che indica che non è stato possibile eseguire il provisioning dell'ambiente dell'agente gestito da Google.

Possibile causa:

Prima che Agent Runtime esegua il deployment del tuo primo agente in un progetto e in una regione, configura le risorse gestite da Google per i tuoi agenti, come gli agenti di servizio e l'ambiente di hosting. Se questa configurazione non va a buon fine, ogni creazione di agente in attesa in quel progetto e in quella regione non va a buon fine con questo errore.

Soluzione consigliata:

Contatta l'assistenza e includi il nome dell'operazione non riuscita nel formato projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.

Soluzioni non applicabili:

  • La ripetizione della creazione dell'agente non risolve questo errore, perché Google deve prima correggere la configurazione non riuscita.
  • La modifica del codice, dei requisiti o di resource_limits dell'agente non è di aiuto, perché l'errore si verifica prima che Agent Runtime esegua il deployment dell'agente.
  • La richiesta di un aumento della quota per il tuo progetto non ha alcun effetto, perché Google gestisce queste risorse.

Errori relativi all'esaurimento delle risorse

Se il deployment non riesce e viene visualizzato lo stato 429, RESOURCE_EXHAUSTED, la causa potrebbe essere uno dei seguenti problemi:

Limite di frequenza o quota API superati

Problema:

Il deployment non riesce con uno stato Error 429 o RESOURCE_EXHAUSTED.

Possibile causa:

Il progetto ha superato i limiti di frequenza delle API o le quote di richiesta in parallelo.

Soluzioni consigliate:

  • Implementa una strategia di backoff esponenziale e nuovi tentativi negli script di deployment.
  • Verifica l'utilizzo attuale rispetto ai limiti nella pagina Quote Google Cloud per l'API Agent Platform.
  • Riduci la frequenza dei deployment simultanei.

Regione temporaneamente al limite della capacità

Problema:

Il deployment non riesce con uno stato 429, RESOURCE_EXHAUSTED e un messaggio che indica che la regione ha temporaneamente raggiunto la capacità per una quantità totale consentita di memoria o CPU.

Possibile causa:

I deployment degli agenti in una regione attingono a un pool di capacità di gestione che Agent Runtime gestisce per tuo conto e che tutti i clienti in quella regione condividono. Quando il pool è esaurito, i nuovi deployment in quella regione non vanno a buon fine finché non si libera capacità.

Questo limite non è una delle quote del progetto. Non viene visualizzata nella paginaGoogle Cloud Quote e non può essere aumentata richiedendo un aumento della quota.

Soluzioni consigliate:

  • Esegui il deployment in un'altra regione supportata. Questo è il modo più rapido per sbloccare un deployment.
  • Riprova più tardi. Una regione con capacità esaurita è un problema temporaneo che di solito si risolve da solo.
  • Richiedi una quantità inferiore di memoria o CPU per l'agente. Un deployment più piccolo potrebbe rientrare nella capacità rimanente.
  • Contatta l'assistenza se i deployment in una regione continuano a non riuscire in questo modo. Anche se non possiamo aumentare il limite, le tue segnalazioni ci aiutano a indirizzare la capacità dove è necessaria.

Soluzioni non applicabili:

  • L'eliminazione degli agenti esistenti non libera capacità per questo limite, perché la capacità non viene consumata solo dal tuo progetto.
  • La richiesta di un aumento della quota non ha alcun effetto, perché il limite non è una quota di progetto.

Il numero massimo di istanze supera il limite regionale

Problema:

Il deployment non riesce con uno stato 429, RESOURCE_EXHAUSTED e un messaggio che indica che spec.deployment_spec.max_instances supera il numero massimo di istanze supportate per la CPU o la memoria richieste nella resource_limits della regione.

Possibile causa:

Quando esegui il deployment di un agente, Agent Runtime moltiplica spec.deployment_spec.max_instances per cpu e memory per istanza in spec.deployment_spec.resource_limits e verifica che l'allocazione di picco di questo singolo agente rientri nel limite regionale del progetto di distribuzione sottostante. Se non specifichi max_instances, Agent Runtime applica un valore predefinito (ad esempio 200), che nelle regioni con limiti inferiori può superare il numero massimo di istanze supportate se moltiplicato per cpu o memory configurati per istanza.

Soluzioni consigliate:

  • Imposta spec.deployment_spec.max_instances sul valore massimo mostrato nel messaggio di errore (o un valore inferiore).
  • Riduci il valore cpu o memory per istanza in spec.deployment_spec.resource_limits.
  • Esegui il deployment dell'agente in un'altra regione supportata con un limite più elevato.

Soluzioni non applicabili:

  • La richiesta di un aumento della quota nella pagina Quote Google Cloud del tuo progetto non ha alcun effetto, perché questo limite viene applicato al progetto di gestione gestito da Google, non al tuo progetto.
  • L'eliminazione di altri agenti nel progetto o un nuovo tentativo senza modificare max_instances o resource_limits non risolve questo errore, perché il controllo valuta l'allocazione di picco del singolo deployment rispetto a un limite statico.

Limitazione della ricerca di Agent Gateway

Problema:

Il deployment o l'aggiornamento di un agente che utilizza un Agent Gateway non riesce con uno stato 429, RESOURCE_EXHAUSTED (REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED) e un messaggio simile al seguente:

The Reasoning Engine could not be created or updated because the request to look up Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` was throttled. Wait about a minute, then try again.

Possibile causa:

Prima dell'inizio di un deployment o di un aggiornamento, Agent Runtime cerca ogni Agent Gateway nel spec.deployment_spec.agent_gateway_config dell'agente per convalidare la richiesta. Questo errore indica che la ricerca è temporaneamente soggetta a limitazione di frequenza. La richiesta viene rifiutata prima dell'inizio del deployment o dell'aggiornamento, pertanto l'agente non viene creato o modificato.

Soluzioni consigliate:

  • Attendi circa un minuto, quindi riprova a eseguire il deployment o l'aggiornamento.
  • Nei workflow automatizzati, riprova a inviare la richiesta con backoff esponenziale.
  • Contatta l'assistenza se l'errore persiste.

Soluzioni non applicabili:

  • La modifica del codice dell'agente, di requirements o di resource_limits non risolve questo errore e il controllo dei log del traffico del container o di Agent Gateway non mostrerà un errore, perché la richiesta viene rifiutata prima che Agent Runtime crei o avvii il container dell'agente.

Errori di accesso a Secret Manager

Problema:

Il deployment non riesce con uno stato 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) e un messaggio simile al seguente:

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

Possibili cause:

  • NOT_FOUND: l'ID secret o l'ID versione specificato in secret_env non esiste in Secret Manager nello stesso progetto dell'agente di cui è stato eseguito il deployment o contiene un errore di battitura.
  • DESTROYED o DISABLED: la versione del secret a cui si fa riferimento in Secret Manager è in uno stato eliminato o disabilitato.
  • PERMISSION_DENIED: il account di servizio utilizzato dall'agente non dispone del ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul secret di riferimento.

Soluzioni consigliate:

  • Per NOT_FOUND, DESTROYED o DISABLED:
    1. Nella pagina Secret Manager del progetto in cui stai eseguendo il deployment dell'agente, verifica che ogni SECRET_ID e VERSION_ID a cui viene fatto riferimento in secret_env esista e sia nello stato Abilitato.
    2. Se una versione di riferimento è stata disattivata o eliminata definitivamente, abilita una versione valida o aggiorna secret_env in modo che faccia riferimento a una versione abilitata.
  • Per PERMISSION_DENIED: concedi il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul secret (o sul progetto contenente il secret) al account di servizio che recupera il secret:
    • Service account predefinito: concedi il ruolo all'agente di servizio AI Platform Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com).
    • Service account personalizzato: concedi il ruolo al service account personalizzato configurato sull'agente.

Errori di associazione di Agent Gateway

Se instradi il traffico tramite Agent Gateway e il deployment o l'aggiornamento dell'agente non va a buon fine prima dell'avvio dell'agente, la causa potrebbe essere uno dei seguenti problemi:

Timeout dell'associazione di Agent Gateway

Problema:

Il deployment o l'aggiornamento di un agente non va a buon fine con uno stato 504, DEADLINE_EXCEEDED (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT) e un messaggio simile al seguente:

The Reasoning Engine timed out waiting for an in-progress operation on shared Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` to finish. Wait for the other operation to complete, then try again.

Possibili cause:

Gli agenti di Agent Runtime nello stesso progetto e nella stessa regione condividono un'associazione a ogni Agent Gateway configurato. La configurazione o l'eliminazione dell'associazione condivisa può richiedere diversi minuti in più rispetto al collegamento di un agente a un'associazione attiva. Il deployment o l'aggiornamento va in timeout se un'altra operazione di associazione o annullamento dell'associazione nello stesso progetto e nella stessa regione non viene completata entro il tempo consentito. Le cause più comuni possono essere:

  • Associazioni iniziali simultanee: associ più agenti a un Agent Gateway nello stesso progetto e nella stessa regione prima che la configurazione condivisa iniziale sia completata.
  • Annullamento dell'associazione in corso: annulli l'associazione o elimini l'ultimo agente associato al gateway nel progetto e nella regione, quindi associ un altro agente allo stesso gateway o a un gateway diverso prima del completamento della disattivazione condivisa.
  • Riprova dopo un'associazione non riuscita: un deployment o un aggiornamento che associa un gateway non va a buon fine e riprovi prima che Agent Runtime termini la pulizia della configurazione non riuscita.

Soluzioni consigliate:

  • Attendi qualche minuto per il completamento di altre operazioni sul gateway indicato nell'errore, quindi riprova a eseguire il deployment o l'aggiornamento.
  • Per associare più agenti in un progetto e in una regione senza un'associazione Agent Gateway attiva, associa prima un agente e attendi che l'operazione venga completata. Quindi esegui il deployment o l'aggiornamento degli agenti rimanenti contemporaneamente.
  • Nei workflow automatizzati, evita di scollegare o eliminare l'ultimo agente associato al gateway in un progetto e in una regione immediatamente prima di associare altri agenti. La rimozione dell'ultimo agente associato al gateway elimina l'associazione condivisa, quindi il deployment successivo ripete la configurazione completa.

Soluzioni non applicabili:

  • Il controllo dei log del container o dei log del traffico di Agent Gateway non mostra un errore per questo errore, perché il timeout si verifica prima che Agent Runtime avvii il container dell'agente.
  • La modifica del codice dell'agente, di requirements o di resource_limits non riduce il tempo di configurazione dell'associazione condivisa.

Se l'associazione del gateway va a buon fine, ma il container non si avvia, consulta Errori durante l'avvio di Agent Runtime.

Binding di Agent Gateway interrotto

Problema:

Il deployment o l'aggiornamento di un agente non riesce con uno stato 409, ABORTED (REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED) e un messaggio simile al seguente:

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because a concurrent shared gateway provisioning operation failed and rolled back. Try again.

Possibile causa:

Gli agenti di Agent Runtime nello stesso progetto e nella stessa regione condividono un'associazione a ogni Agent Gateway configurato. Quando associ più agenti allo stesso gateway prima che sia configurata l'associazione condivisa, un deployment o un aggiornamento configura l'associazione e gli altri attendono. Se il deployment o l'aggiornamento non va a buon fine prima che l'associazione sia pronta, Agent Runtime esegue il rollback dell'associazione e ogni deployment o aggiornamento in attesa non va a buon fine con questo errore. Il deployment o l'aggiornamento che ha configurato l'associazione segnala il proprio errore, che potrebbe non essere correlato ad Agent Gateway.

Soluzioni consigliate:

Soluzioni non applicabili:

  • Il controllo dei log dei container o dei log del traffico di Agent Gateway non mostra un errore per questo errore, perché l'errore si verifica prima che Agent Runtime avvii il container dell'agente.
  • La modifica del codice dell'agente, di requirements o di resource_limits non è di aiuto, perché questo errore è stato causato da un altro deployment o aggiornamento, non dal tuo agente.

Binding di Agent Gateway temporaneamente non disponibile

Problema:

Il deployment o l'aggiornamento di un agente non riesce con uno stato 503, UNAVAILABLE (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE) e un messaggio simile al seguente:

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because network provisioning encountered a transient upstream service error. Try again.

Possibile causa:

Quando il primo agente di un progetto e di una regione si associa a un Agent Gateway, Agent Runtime configura le risorse di networking condivise gestite da Google che connettono gli agenti al gateway. Se un servizio Google Cloudda cui dipende questa configurazione continua a restituire errori temporanei dopo diversi tentativi automatici, Agent Runtime esegue il rollback della configurazione e il deployment o l'aggiornamento non riesce con questo errore. Altri deployment o aggiornamenti che erano in attesa della stessa configurazione non vanno a buon fine con uno stato 409, ABORTED. Consulta Associazione di Agent Gateway interrotta.

Soluzioni consigliate:

  • Attendi almeno 10 minuti affinché Agent Runtime completi il rollback della configurazione non riuscita, quindi riprova a eseguire il deployment o l'aggiornamento. Un nuovo tentativo che inizia prima del completamento del rollback può non riuscire con uno stato 504, DEADLINE_EXCEEDED. Consulta Timeout dell'associazione di Agent Gateway.
  • Se l'errore persiste dopo diversi tentativi, contatta l'assistenza e includi il nome dell'operazione non riuscita nel formato projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.

Soluzioni non applicabili:

  • La modifica del codice dell'agente, di requirements o di resource_limits non è di aiuto, perché l'errore si verifica prima che Agent Runtime esegua il deployment dell'agente.
  • La richiesta di un aumento della quota per il tuo progetto non ha alcun effetto, perché Google gestisce queste risorse di networking.

Risorse di assistenza

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