Risolvere i problemi di configurazione dell'ambiente per Agent Runtime

Questo documento descrive come risolvere gli errori che potresti riscontrare durante la configurazione di un ambiente per Agent Runtime. Vengono descritti i passaggi per la risoluzione dei problemi di importazione dei pacchetti.

Errori durante l'importazione dell'SDK Agent Platform

Se non riesci a importare l'SDK Agent Platform per Python, il motivo potrebbe essere uno dei seguenti problemi:

Versione obsoleta dell'SDK Agent Platform per Python

Problema:

Ricevi un messaggio di errore simile al seguente:

ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'

o

ImportError: cannot import name 'agent_angines' from 'vertexai'

Possibile causa:

Ciò potrebbe accadere se la versione del pacchetto google-cloud-aiplatform è precedente a 1.82.0 (per agent_engines) o 1.47.0 (per reasoning_engines). Per controllare la versione del pacchetto google-cloud-aiplatform, 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

Verifica che la versione aggiornata sia 1.82.0 o successive eseguendo questo comando:

pip show google-cloud-aiplatform

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

Errori di autorizzazione 401

Problema:

Ricevi un messaggio di errore simile al seguente:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

OPPURE

Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.

Possibile causa:

Per impostazione predefinita, quando utilizzi l'identità dell'agente con Agent Runtime, vengono utilizzati token di accesso associati al certificato per l'autenticazione per impedire il furto di token. Un errore 401 può verificarsi in fase di runtime in uno dei seguenti due scenari:

1. Utente o agente che tenta di utilizzare un token di accesso al di fuori del contesto in cui è stato emesso, ad esempio passando il token tra gli agenti.
2. L'agente chiama un endpoint API non compatibile con mTLS, ad esempio telemetry.googleapis.com anziché telemetry.mtls.googleapis.com.

Soluzione consigliata:

Per lo scenario n. 1, se hai un motivo legittimo per condividere i token tra gli agenti, puoi disattivare il criterio di accesso sensibile al contesto (CAA) predefinito. Questa azione è fortemente sconsigliata, in quanto lascia un agente vulnerabile al furto di credenziali.

Disattiva la policy CAA predefinita impostando la seguente variabile di ambiente quando crei l'istanza di Agent Runtime:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Per lo scenario n. 2, puoi impostare in modo simile la variabile GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES su False per consentire agli agenti di utilizzare gli endpoint API non mTLS come soluzione temporanea. In questo caso, il problema di fondo potrebbe essere un problema noto di ADK.