Fehlerbehebung bei der Einrichtung der Umgebung für die Laufzeit für KI-Agenten

In diesem Dokument wird beschrieben, wie Sie Fehler beheben, die beim Einrichten einer Umgebung für die Agent Runtime auftreten können. Es enthält Schritte zur Fehlerbehebung bei Problemen mit dem Paketimport.

Fehler beim Importieren des Agent Platform SDK

Wenn Sie das Agent Platform SDK für Python nicht importieren können, kann das folgende Ursachen haben:

Veraltete Version des Agent Platform SDK für Python

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

oder

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

Mögliche Ursache:

Dies kann auftreten, wenn die Version Ihres google-cloud-aiplatform-Pakets älter als 1.82.0 (für agent_engines) oder 1.47.0 (für reasoning_engines) ist. Führen Sie den folgenden Befehl im Terminal aus, um die Version Ihres google-cloud-aiplatform-Pakets zu prüfen:

pip show google-cloud-aiplatform

Empfohlene Lösung:

Führen Sie im Terminal den folgenden Befehl aus, um das google-cloud-aiplatform-Paket zu aktualisieren:

pip install google-cloud-aiplatform --upgrade

Prüfen Sie mit dem folgenden Befehl, ob Ihre aktualisierte Version 1.82.0 oder höher ist:

pip show google-cloud-aiplatform

Wenn Sie sich in einer Notebookinstanz befinden (z. B. Jupyter, Colab oder Workbench), müssen Sie möglicherweise Ihre Laufzeit neu starten, um die aktualisierten Pakete verwenden zu können.

401‑Autorisierungsfehler

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

ODER

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.

Mögliche Ursache:

Wenn Sie die Agentenidentität mit der Agentenlaufzeit verwenden, werden standardmäßig an Zertifikate gebundene Zugriffstokens zur Authentifizierung verwendet, um Token-Diebstahl zu verhindern. Ein 401-Fehler kann zur Laufzeit in einem der folgenden beiden Szenarien auftreten:

  1. Nutzer oder KI‑Agent versuchen, ein Zugriffstoken außerhalb des Kontexts zu verwenden, in dem es ausgestellt wurde, z. B. durch Weitergabe des Tokens zwischen KI‑Agenten.
  2. Der Agent ruft einen API-Endpunkt auf, der nicht mit mTLS kompatibel ist, z. B. telemetry.googleapis.com anstelle von telemetry.mtls.googleapis.com.

Empfohlene Lösung:

Wenn Sie im ersten Szenario einen legitimen Grund haben, Tokens zwischen Agents zu teilen, können Sie die standardmäßige Richtlinie für den kontextsensitiven Zugriff (Context-Aware Access, CAA) deaktivieren. Diese Aktion wird jedoch dringend abgeraten, da ein Agent dadurch anfällig für Anmeldediebstahl wird.

Sie können die Standard-CAA-Richtlinie deaktivieren, indem Sie beim Erstellen Ihrer Agent Runtime-Instanz die folgende Umgebungsvariable festlegen:

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

Für Szenario 2 können Sie die Variable GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES auf False setzen, damit Kundenservicemitarbeiter die API-Endpunkte ohne gegenseitige TLS-Authentifizierung als temporären Workaround verwenden können. In diesem Fall könnte das zugrunde liegende Problem ein bekanntes Problem mit dem ADK sein.