Fehlerbehebung bei der Bereitstellung eines Agents

In diesem Dokument wird beschrieben, wie Sie Fehler beheben können, die beim Bereitstellen eines KI-Agenten in Agent Runtime auftreten können. Es werden verschiedene häufige Probleme behandelt, darunter Serialisierungsfehler, Berechtigungsfehler und Verstöße gegen VPC-SC-Grenzen.

Hinweis: Wenn Sie Fehlerlogs von Agenten suchen und filtern möchten, verwenden Sie den Log-Explorer, wählen Sie RESOURCE TYPE für „Vertex AI Reasoning Engine“ aus und wählen Sie den entsprechenden RESOURCE CONTAINER-Wert (d.h. die Projektnummer) und den REASONING ENGINE ID-Wert aus.

Fehler beim Erstellen und Starten von Containern

Wenn die Bereitstellung fehlschlägt, während Agent Runtime den Container des Agenten erstellt oder startet, kann das an einem der folgenden Probleme liegen:

Container-Image-Build fehlgeschlagen

Problem:

Die Bereitstellung schlägt mit dem Status 400, INVALID_ARGUMENT (REASONING_ENGINE_BUILD_FAILED) und einer Meldung wie der folgenden fehl:

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

Mögliche Ursachen:

Wenn Sie einen KI-Agenten aus einem Agentenobjekt, aus Quelldateien oder aus einem Dockerfile bereitstellen, erstellt Agent Runtime ein Container-Image für den KI-Agenten. Der Build schlägt fehl, wenn einer der folgenden Schritte fehlschlägt:

  • Paketanforderungen werden installiert: Ein Paket in requirements oder in der Anforderungsdatei Ihrer Quelldateien ist nicht vorhanden, pinnt eine nicht vorhandene Version, steht im Konflikt mit einem anderen Paket oder unterstützt die Python-Version des Agenten nicht.
  • Lokales Wheel installieren: Eine in requirements aufgeführte Wheel-Datei ist nicht in extra_packages enthalten und kann daher nicht installiert werden.
  • Installationsskripts ausführen: Ein Skript im Verzeichnis installation_scripts wird mit einem Fehler beendet.
  • Dockerfile erstellen: Wenn Sie ein Dockerfile (image_spec) bereitstellen, schlägt eine Anweisung in Ihrem Dockerfile fehl.

Empfohlene Lösungen:

  • Prüfen Sie die Build-Logs, die im Feld logs_url der Fehlermetadaten verlinkt sind, um den fehlgeschlagenen Schritt zu finden. Build-Logeinträge enthalten die Log-ID reasoning_engine_build. Informationen zum Abfragen der Logs finden Sie unter Abfragen erstellen.
  • Wenn Sie den Fehler lokal reproduzieren möchten, installieren Sie dieselben Anforderungen in einer neuen virtuellen Umgebung, die die Python-Version des bereitgestellten KI-Agenten verwendet, und beheben Sie alle Fehler, die von pip gemeldet werden:

    python -m venv agent-env
    agent-env/bin/pip install -r requirements.txt
  • Damit die Versionen, die Sie lokal getestet haben, im Build installiert werden, pinnen Sie Ihre Paketversionen an. Weitere Informationen finden Sie unter Paketanforderungen definieren.

  • Wenn Sie ein lokales Wheel installieren, fügen Sie es sowohl in requirements als auch in extra_packages ein. Weitere Informationen finden Sie unter Zusätzliche Pakete definieren.

  • Wenn Sie Installationsskripts verwenden, achten Sie darauf, dass jedes Skript erfolgreich beendet wird, wenn es mit Root-Berechtigungen in einer sauberen Umgebung ausgeführt wird. Weitere Informationen finden Sie unter Build-Optionen definieren.

  • Wenn Sie die Bereitstellung über ein Dockerfile vornehmen, erstellen Sie das Container-Image lokal aus denselben Quelldateien (z. B. mit docker build) und korrigieren Sie alle fehlerhaften Anweisungen.

Nicht zutreffende Lösungen:

  • Wenn Sie die Bereitstellung wiederholen, ohne die Anforderungen, Installationsskripts oder das Dockerfile zu ändern, schlägt sie auf dieselbe Weise fehl, da der Build dieselben Schritte ausführt.

Zeitüberschreitung beim Erstellen des Container-Images

Problem:

Die Bereitstellung schlägt mit dem Status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) und einer Meldung fehl, dass das Container-Image des Agents nicht rechtzeitig erstellt wurde.

Mögliche Ursachen:

Wenn Sie aus Quelldateien bereitstellen, erstellt Agent Runtime ein Container-Image, das Ihren Code und seine Abhängigkeiten installiert. Die Bereitstellung schlägt fehl, wenn der Build noch ausgeführt wird, wenn die zulässige Zeit abgelaufen ist. Builds dauern in der Regel zu lange, weil die Abhängigkeiten installiert werden, z. B.:

  • Eine lange Liste von Paketen in requirements, einschließlich derer, die der Agent nicht verwendet.
  • Pakete ohne vorkonfigurierte Wheels für die Build-Umgebung, die während des Builds aus der Quelle kompiliert werden.
  • Nicht angepinnte oder lose angepinnte Versionen, die die Auflösung von Abhängigkeiten verlangsamen.

Empfohlene Lösungen:

  • Prüfen Sie die Build-Logs, die im Feld logs_url der Fehlermetadaten verlinkt sind, um zu sehen, welcher Schritt ausgeführt wurde, als der Build gestoppt wurde.
  • Entfernen Sie unnötige Abhängigkeiten und pinnen Sie die Versionen aller erforderlichen Pakete an.
  • Priorisieren Sie Pakete und Versionen, die vordefinierte Wheels veröffentlichen, damit während des Builds nichts kompiliert wird.
  • Wiederholen Sie die Bereitstellung. Ein Build kann gelegentlich aus Gründen, die nichts mit Ihrem Code zu tun haben, länger als gewöhnlich dauern.

Container konnte nicht gestartet werden

Problem:

Die Bereitstellung schlägt mit dem Status 400, INVALID_ARGUMENT (REASONING_ENGINE_CONTAINER_FAILED_TO_START) und einer Meldung fehl, dass der Container des Agents nicht innerhalb des Startzeitlimits gestartet wurde.

Mögliche Ursachen:

Die Agent Runtime startet Ihren KI-Agenten in einem Container und wartet, bis er Anfragen annimmt. Das Deployment schlägt fehl, wenn der Container vor dem Startzeitlimit beendet wird oder nicht reagiert. Häufige Ursachen:

  • Fehlende Abhängigkeit: Ihr Agent importiert ein Paket, das nicht in requirements oder extra_packages aufgeführt ist. Daher schlägt das Laden des Agents mit einem Fehler wie ModuleNotFoundError fehl.
  • Paketversionskonflikt: Die in der bereitgestellten Umgebung installierten Pakete unterscheiden sich von denen in Ihrer Entwicklungsumgebung. Daher schlägt das Laden des Agenten mit einem Fehler wie AttributeError: Can't get attribute fehl. Weitere Informationen finden Sie unter Serialisierungsfehler.
  • Fehler bei der Initialisierung: Die Methode set_up() Ihres Agents oder anderer Code, der beim Laden des Agents ausgeführt wird, löst eine Ausnahme aus oder wartet auf eine Ressource, die nicht erreichbar ist.
  • Langsame Initialisierung: Das Laden des KI-Agenten dauert länger als das Zeitlimit für den Start.
  • Benutzerdefinierter Container überwacht nicht: Ein benutzerdefinierter Container muss HTTP-Anfragen an 0.0.0.0 auf Port 8080 überwachen. Weitere Informationen finden Sie im Laufzeitvertrag.
  • Agent Gateway blockiert den Start: Wenn Sie Traffic über Agent Gateway weiterleiten, schlägt der Start fehl, wenn Identity-Aware Proxy (IAP) Initialisierungsaufrufe blockiert, wenn der Agentenidentität die erforderlichen Rollen fehlen oder wenn ein benutzerdefinierter Container dem Root-Zertifikat des Gateways nicht vertraut. Weitere Informationen finden Sie unter Fehler beim Start der Agent Runtime und Mit benutzerdefiniertem Container (BYOC) bereitgestellter Agent kann keine Verbindung zum Agent Gateway herstellen.

Empfohlene Lösungen:

  • Prüfen Sie die Logs des Agents, die im Feld logs_url der Fehlermetadaten verlinkt sind, um den Fehler zu finden, der den Container gestoppt hat. Weitere Informationen finden Sie unter Logs für einen Agent ansehen.
  • Fügen Sie fehlende Pakete zu requirements oder extra_packages hinzu und pinnen Sie die Versionen an, die Sie in der Entwicklung verwenden.
  • Wenn Sie den Fehler lokal reproduzieren möchten, installieren Sie nur die in requirements aufgeführten Pakete in einer sauberen Umgebung mit derselben Python-Version. Importieren und instanziieren Sie dann Ihren Agenten.
  • Verschieben Sie langsame oder fehleranfällige Aufgaben, z. B. das Herstellen einer Verbindung zu externen Diensten, aus der Agent-Initialisierung.
  • Achten Sie bei einem benutzerdefinierten Container darauf, dass der Server 0.0.0.0 und den Port in der Umgebungsvariable PORT (Standard: 8080) überwacht.

Nicht zutreffende Lösungen:

  • Wenn Sie die Bereitstellung wiederholen, ohne den Agenten oder seine Abhängigkeiten zu ändern, schlägt sie in der Regel auf dieselbe Weise fehl, da die Ursache im Agenten-Code oder in seiner Umgebung liegt.

Container wurde nicht rechtzeitig gestartet

Problem:

Die Bereitstellung schlägt mit dem Status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) und der Meldung fehl, dass der Container des Agents nicht rechtzeitig gestartet wurde.

Mögliche Ursachen:

Nachdem das Image erstellt wurde, startet Agent Runtime den Container des KI-Agenten und wartet, bis er bereit ist, Anfragen zu verarbeiten. Die Bereitstellung schlägt fehl, wenn der Container noch gestartet wird, wenn die zulässige Zeit abgelaufen ist. Häufige Ursachen sind:

  • Langsame Arbeit beim Import, z. B. das Laden großer Modelle oder Dateien, wenn die Module des KI-Agenten importiert werden.
  • Langsame oder blockierende Arbeit in der Methode set_up() des Agents, z. B. Netzwerkaufrufe, die auf einen nicht erreichbaren Dienst warten.

Empfohlene Lösungen:

  • Prüfen Sie die Containerlogs, die im Feld logs_url der Fehlermetadaten verlinkt sind, um zu sehen, wo der Startvorgang hängen geblieben ist.
  • Verschieben Sie die teure Initialisierung aus der Modulimportzeit und minimieren Sie die Anzahl der Schritte in set_up() schnell. Verschieben Sie Arbeiten, die für die erste Anfrage nicht erforderlich sind.
  • Achten Sie darauf, dass alle Dienste, die der Agent beim Start aufruft, vom Agenten erreichbar sind, und legen Sie Zeitlimits für diese Aufrufe fest, damit sie den Start nicht unbegrenzt blockieren können.
  • Wenn die Containerlogs zeigen, dass der Agent normal gestartet wurde, wiederholen Sie die Bereitstellung. Der Start kann gelegentlich aus Gründen, die nichts mit Ihrem Code zu tun haben, länger als gewöhnlich dauern.

Fehler bei vordefinierten Vorlagen

Wenn während der Bereitstellung Probleme mit der LangchainAgent-Vorlage auftreten, kann dies an einem der Probleme in diesem Abschnitt liegen.

Interne Serverfehler

Problem:

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

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

Leider ist dies ein Sammelfehler für alle Probleme mit dem Container zur Laufzeit. Die mögliche Ursache ist einer von vielen möglichen Fehlern.

Mögliche Ursache(n)

  • Dirty-Status am LangchainAgent. Dies kann passieren, wenn .set_up() auf einem LangchainAgent aufgerufen wurde, bevor der Agent bereitgestellt wurde.
  • Inkonsistente Paketversionen. Dies kann auftreten, wenn sich die in der Entwicklungsumgebung installierten Pakete von den Paketen unterscheiden, die in der Remote-Umgebung in Agent Runtime installiert sind.

Empfohlene Lösunge(n)

  • Dirty-Status am LangchainAgent. Instanziieren Sie eine neue Instanz der LangchainAgent oder entfernen Sie agent.set_up() aus dem Code, bevor Sie den Agenten bereitstellen.
  • Nicht übereinstimmende Paketspezifikationen Weitere Informationen finden Sie im Abschnitt zur Behebung von Serialisierungsfehlern.

Serialisierungsfehler

Im Allgemeinen ist es wichtig, dass die „lokale“ und die „Remote“-Umgebung bei der Bereitstellung des Agenten synchron sind. Sie können dies sicherstellen, indem Sie requirements= angeben, wenn Sie den Agenten bereitstellen.

Wenn Sie Probleme mit der Serialisierung haben (Fehler im Zusammenhang mit „pickle“ oder „Pickling“ sind Synonyme für „Serialisierung“), kann dies an einem der in diesem Abschnitt beschriebenen Probleme liegen.

Pydantic-Version

Problem:

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

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

Mögliche Ursache:

Dies kann auftreten, wenn Ihr pydantic-Paket älter als Version 2.6.4 ist. Führen Sie folgenden Befehl in Ihrem Terminal aus, um zu prüfen, welche Version Sie verwenden:

pip show pydantic

Empfohlene Lösung:

Aktualisieren Sie das Paket, indem Sie im Terminal den folgenden Befehl ausführen:

pip install pydantic --upgrade

Führen Sie den folgenden Befehl in Ihrem Terminal aus, um zu prüfen, ob Sie die Version 2.6.4 oder höher verwenden:

pip show pydantic

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

Cloudpickle-Version

Problem:

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

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

Mögliche Ursache:

Das kann passieren, wenn die Version Ihres cloudpickle-Pakets in Ihrer Entwicklungsumgebung und Ihrer Bereitstellungsumgebung unterschiedlich ist. Führen Sie den folgenden Befehl in Ihrem Terminal aus, um zu prüfen, welche Version Sie in der Entwicklung verwenden:

pip show cloudpickle

Empfohlene Lösung:

Stellen Sie dieselbe Version von cloudpickle in beiden Umgebungen bereit, z. B. in Ihrer lokalen Entwicklungsumgebung und im remote bereitgestellten Agenten, indem Sie beim Bereitstellen des Agenten requirements= angeben.

Interne Serverfehler

Problem:

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

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

Mögliche Ursache:

Das kann passieren, wenn sich sys_version= von der Entwicklungsumgebung unterscheidet, wenn Sie den Agenten bereitstellen.

Empfohlene Lösung:

Nachdem Sie den Agent bereitgestellt haben, sollten Sie sys_version= aus den Eingabeargumenten entfernen. Wenn weiterhin Probleme auftreten, reichen Sie einen Fehlerbericht ein.

Cloud Storage-Bucket-Fehler

Wenn Probleme mit dem Cloud Storage-Staging-Bucket auftreten, der zum Zeitpunkt der Bereitstellung zum Erfassen und Hochladen Ihres Bots verwendet wird, kann das an einem der folgenden Probleme liegen:

Berechtigungsfehler

Empfohlene Lösung:

Wenn Sie einen bereits vorhandenen Bucket verwenden möchten, achten Sie darauf, dass das Hauptkonto, das für die Verwendung der Agent Platform authentifiziert ist (entweder Sie selbst oder ein Dienstkonto), Storage Admin-Zugriff auf den Bucket hat, und gewähren Sie Berechtigungen für das Dienstkonto.

Alternativ können Sie bei der Bereitstellung des KI-Agenten einen neuen Bucket angeben und das SDK erstellt den Bucket mit den erforderlichen Berechtigungen.

Wenn weiterhin Probleme auftreten, reichen Sie einen Fehlerbericht ein.

Unterverzeichnis des Cloud Storage-Buckets wird nicht erstellt

Problem:

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

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.

(Der 404-Fehler tritt auf, wenn das System versucht, in einen nicht vorhandenen Ordner zu kopieren.)

Mögliche Ursache:

Das liegt wahrscheinlich an einem Problem mit der Stringinterpolation in google-cloud-aiplatform-Versionen, die älter als 1.49.0 sind. Dieser Fehler wurde in höheren Versionen behoben. Führen Sie in Ihrem Terminal den folgenden Befehl aus, um zu prüfen, welche Version von google-cloud-aiplatform Sie verwenden:

pip show google-cloud-aiplatform

Empfohlene Lösung:

Aktualisieren Sie das Paket, indem Sie im Terminal den folgenden Befehl ausführen:

pip install google-cloud-aiplatform --upgrade

Prüfen Sie, ob Sie die Version 1.49.0 oder höher von google-cloud-aiplatform verwenden. Führen Sie dazu den folgenden Befehl in Ihrem Terminal aus:

pip show google-cloud-aiplatform

Wenn Sie eine Notebookinstanz nutzen, z. B. Jupyter, Colab oder Workbench, müssen Sie möglicherweise Ihre Laufzeit neu starten, bevor Sie die aktualisierten Pakete verwenden können.

VPC-SC-Verstoßfehler

Wenn Probleme mit VPC-SC auftreten, kann dies eine der folgenden Ursachen haben:

Berechtigungsfehler

Problem:

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

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

oder:

Request is prohibited by organization's policy.

Mögliche Ursache:

Dies wird wahrscheinlich durch fehlende erforderliche Regeln für eingehenden Traffic im VPC-SC-Perimeter verursacht.

Empfohlene Lösung:

Wenn Sie die Agent Platform in einer VPC-SC-Umgebung verwenden, müssen Sie in Ihrem Perimeter eine Regel für eingehenden Traffic erstellen, um eingehenden Traffic vom Reasoning Engine-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) zum Dienst storage.googleapis.com und zum Dienst artifactregistry.googleapis.com zuzulassen.

Fehler bei benutzerdefinierten Dienstkonten

Wenn Sie Probleme mit Dienstkonten haben, kann dies eine der folgenden Ursachen haben:

Als Dienstkonto agieren

Problem:

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

You do not have permission to act as service_account.

Mögliche Ursache:

Möglicherweise haben Sie nicht die Berechtigung iam.serviceAccounts.actAs für das benutzerdefinierte Dienstkonto, das für die Bereitstellung verwendet wird. In einem Multi-Agenten-System mit mehreren benutzerdefinierten Dienstkonten kann ein Agent-Autor oder -Deployer als einige der Dienstkonten fungieren. Wenn Sie das falsche Dienstkonto verwenden, ist dieser Fehler das erwartete Verhalten.

Dieser Fehler kann auch auftreten, wenn sich das benutzerdefinierte Dienstkonto in einem anderen Projekt als dem befindet, in dem Sie den Agenten bereitstellen, und die Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage im Dienstkontoprojekt erzwungen wird.

Eine vollständige Liste der erforderlichen Konfigurationen für dieses Szenario finden Sie unter Projektübergreifendes benutzerdefiniertes Dienstkonto.

Empfohlene Lösung:

Achten Sie darauf, dass Sie das gewünschte Dienstkonto verwenden. Prüfen Sie, ob Sie die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser) für dieses Dienstkonto haben. Wenn nicht, bitten Sie Ihren Administrator, Ihnen die Rolle für dieses Dienstkonto zu gewähren.

Wenn Sie sich im projektübergreifenden Szenario befinden, prüfen Sie, ob für Ihr Dienstkontoprojekt die Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage erzwungen wird. Bitten Sie in diesem Fall Ihren Administrator, die Richtlinie zu deaktivieren.

Metadatenserver nicht verfügbar

Problem:

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

ServiceUnavailable: 503 Getting metadata from plugin failed with error

oder

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

Mögliche Ursache:

Das kann passieren, wenn sich das benutzerdefinierte Dienstkonto und Ihr Agent in verschiedenen Projekten befinden und der KI Platform Reasoning Engine-Dienst-Agent nicht die Berechtigung iam.serviceAccounts.getAccessToken für das benutzerdefinierte Dienstkonto hat.

Eine vollständige Liste der erforderlichen Konfigurationen für dieses Szenario finden Sie unter Projektübergreifendes benutzerdefiniertes Dienstkonto.

Empfohlene Lösung:

Bitten Sie Ihren Administrator, dem KI-Plattform Reasoning Engine-Dienst-Agent des Agent-Projekts die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) für das benutzerdefinierte Dienstkonto zuzuweisen.

Der KI-Plattform Reasoning Engine-Dienst-Agent sollte sich in demselben Projekt befinden, das Sie zum Bereitstellen Ihres Agenten verwenden. Die IAM-Bindung der Rollenzuweisung sollte sich in dem Projekt befinden, in dem sich das benutzerdefinierte Dienstkonto befindet.

Bereitstellung der Umgebung fehlgeschlagen

Problem:

Das Erstellen eines KI-Agenten schlägt mit dem Status 500, INTERNAL (REASONING_ENGINE_PROVISIONING_FAILED) und der Meldung fehl, dass die von Google verwaltete Umgebung des KI-Agenten nicht bereitgestellt werden konnte.

Mögliche Ursache:

Bevor Agent Runtime Ihren ersten Agenten in einem Projekt und einer Region bereitstellt, werden von Google verwaltete Ressourcen für Ihre Agenten eingerichtet, z. B. Dienst-Agenten und die Hosting-Umgebung. Wenn diese Einrichtung fehlschlägt, schlägt jede ausstehende Agentenerstellung in diesem Projekt und dieser Region mit diesem Fehler fehl.

Empfohlene Lösung:

Wenden Sie sich an den Support und geben Sie den Namen des fehlgeschlagenen Vorgangs im Format projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID an.

Nicht zutreffende Lösungen:

  • Ein erneuter Versuch, den Agenten zu erstellen, behebt diesen Fehler nicht, da Google zuerst die fehlerhafte Einrichtung beheben muss.
  • Das Ändern des Codes, der Anforderungen oder der resource_limits Ihres KI-Agenten hilft nicht, da der Fehler auftritt, bevor die Agent Runtime Ihren KI-Agenten bereitstellt.
  • Eine Kontingenterhöhung für Ihr Projekt hat keine Auswirkungen, da Google diese Ressourcen verwaltet.

Fehler vom Typ „Ressource erschöpft“

Wenn Ihre Bereitstellung mit dem Status 429, RESOURCE_EXHAUSTED fehlschlägt, kann eines der folgenden Probleme die Ursache sein:

API-Ratenbegrenzung oder -Kontingent überschritten

Problem:

Die Bereitstellung schlägt mit dem Status Error 429 oder RESOURCE_EXHAUSTED fehl.

Mögliche Ursache:

Das Projekt hat die API-Ratenbegrenzungen oder die Kontingente für gleichzeitige Anfragen überschritten.

Empfohlene Lösungen:

  • Implementieren Sie in Bereitstellungsskripts eine Strategie für exponentiellen Backoff und Wiederholungsversuche.
  • Prüfen Sie die aktuelle Nutzung im Vergleich zu den Limits auf der Seite Google Cloud „Kontingente“ für die Agent Platform API.
  • Reduzieren Sie die Häufigkeit gleichzeitiger Bereitstellungen.

Region vorübergehend ausgelastet

Problem:

Die Bereitstellung schlägt mit dem Status 429, RESOURCE_EXHAUSTED und einer Meldung fehl, dass die Region vorübergehend die Kapazität für die zulässige Gesamtmenge an Arbeitsspeicher oder CPU erreicht hat.

Mögliche Ursache:

KI-Agenten-Bereitstellungen in einer Region greifen auf einen Pool von Bereitstellungskapazität zurück, den Agent Runtime in Ihrem Namen verwaltet und den alle Kundenunternehmen in dieser Region gemeinsam nutzen. Wenn der Pool erschöpft ist, schlagen neue Bereitstellungen in dieser Region fehl, bis wieder Kapazität frei wird.

Dieses Limit ist keines der Kontingente Ihres Projekts. Es wird nicht auf der SeiteGoogle Cloud Kontingente angezeigt und kann nicht durch eine Anfrage zur Kontingenterhöhung erhöht werden.

Empfohlene Lösungen:

  • Stellen Sie die Anwendung in einer anderen unterstützten Region bereit. Dies ist die schnellste Möglichkeit, die Blockierung einer Bereitstellung aufzuheben.
  • Versuchen Sie es später noch einmal. Eine Region, die ihre Kapazitätsgrenze erreicht hat, ist ein vorübergehendes Problem, das sich in der Regel von selbst löst.
  • Fordern Sie weniger Arbeitsspeicher oder CPU für Ihren Agenten an. Eine kleinere Bereitstellung passt möglicherweise in die verbleibende Kapazität.
  • Wenden Sie sich an den Support, wenn Bereitstellungen in einer Region weiterhin auf diese Weise fehlschlagen. Wir können das Limit zwar nicht erhöhen, aber Ihre Berichte helfen uns, die Kapazität dorthin zu lenken, wo sie benötigt wird.

Nicht zutreffende Lösungen:

  • Durch das Löschen Ihrer vorhandenen Agenten wird keine Kapazität für dieses Limit freigegeben, da die Kapazität nicht nur von Ihrem Projekt verbraucht wird.
  • Die Anforderung einer Kontingenterhöhung hat keine Auswirkungen, da das Limit kein Projektkontingent ist.

Maximale Anzahl von Instanzen überschreitet regionales Limit

Problem:

Die Bereitstellung schlägt mit dem Status 429, RESOURCE_EXHAUSTED und einer Meldung fehl, dass spec.deployment_spec.max_instances die maximale Anzahl von Instanzen überschreitet, die für die angeforderte CPU oder den angeforderten Arbeitsspeicher in der resource_limits der Region unterstützt werden.

Mögliche Ursache:

Wenn Sie einen Agenten bereitstellen, multipliziert Agent Runtime spec.deployment_spec.max_instances mit den instanzspezifischen cpu und memory in spec.deployment_spec.resource_limits und prüft, ob die Spitzenzuweisung dieses einzelnen Agenten innerhalb des regionalen Limits des zugrunde liegenden Bereitstellungsprojekts liegt. Wenn Sie max_instances nicht angeben, wendet Agent Runtime einen Standardwert an (z. B. 200). Dieser kann in Regionen mit niedrigeren Limits die maximal unterstützten Instanzen überschreiten, wenn er mit dem konfigurierten cpu oder memory pro Instanz multipliziert wird.

Empfohlene Lösungen:

  • Setzen Sie spec.deployment_spec.max_instances auf den in der Fehlermeldung angezeigten Höchstwert (oder einen niedrigeren Wert).
  • Reduzieren Sie den Wert für cpu oder memory pro Instanz in spec.deployment_spec.resource_limits.
  • Stellen Sie den Agenten in einer anderen unterstützten Region mit einem höheren Limit bereit.

Nicht zutreffende Lösungen:

  • Eine Erhöhung des Kontingents auf der Seite Google Cloud „Kontingente“ Ihres Projekts anzufordern, hat keine Auswirkungen, da dieses Limit für das von Google verwaltete Bereitstellungsprojekt und nicht für Ihr Projekt gilt.
  • Das Löschen anderer Agents in Ihrem Projekt oder ein erneuter Versuch ohne Änderung von max_instances oder resource_limits behebt diesen Fehler nicht, da bei der Prüfung die Spitzenzuweisung der einzelnen Bereitstellung mit einem statischen Limit verglichen wird.

Agent Gateway-Suche gedrosselt

Problem:

Das Bereitstellen oder Aktualisieren eines KI-Agenten, der ein KI-Agenten-Gateway verwendet, schlägt mit dem Status 429, RESOURCE_EXHAUSTED (REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED) und einer Meldung ähnlich der folgenden fehl:

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.

Mögliche Ursache:

Bevor eine Bereitstellung oder Aktualisierung beginnt, sucht Agent Runtime nach jedem Agent Gateway in der spec.deployment_spec.agent_gateway_config des KI-Agenten, um die Anfrage zu validieren. Dieser Fehler bedeutet, dass die Suche vorübergehend einer Ratenbegrenzung unterliegt. Die Anfrage wird abgelehnt, bevor die Bereitstellung oder Aktualisierung beginnt. Ihr Agent wird also nicht erstellt oder geändert.

Empfohlene Lösungen:

  • Warten Sie etwa eine Minute und versuchen Sie dann noch einmal, die Bereitstellung oder Aktualisierung durchzuführen.
  • Wiederholen Sie die Anfrage in automatisierten Workflows mit exponentiellem Backoff.
  • Wenden Sie sich an den Support, wenn der Fehler weiterhin auftritt.

Nicht zutreffende Lösungen:

  • Das Ändern des Codes, der requirements oder der resource_limits Ihres KI-Agenten behebt diesen Fehler nicht. Auch in den Traffic-Logs des Containers oder des Agent Gateways wird kein Fehler angezeigt, da die Anfrage abgelehnt wird, bevor die Agent Runtime den Container Ihres KI-Agenten erstellt oder startet.

Secret Manager-Zugriffsfehler

Problem:

Die Bereitstellung schlägt mit dem Status 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) und einer Meldung wie der folgenden fehl:

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).

Mögliche Ursachen:

  • NOT_FOUND: Die in secret_env angegebene Secret-ID oder Versions-ID ist im Secret Manager im selben Projekt wie der bereitgestellte Agent nicht vorhanden oder enthält einen Tippfehler.
  • DESTROYED oder DISABLED: Die referenzierte Secret-Version in Secret Manager ist gelöscht oder deaktiviert.
  • PERMISSION_DENIED: Das vom Agent verwendete Dienstkonto hat nicht die Rolle „Secret Manager Secret Accessor“ (roles/secretmanager.secretAccessor) für das referenzierte Secret.

Empfohlene Lösungen:

  • Für NOT_FOUND, DESTROYED oder DISABLED:
    1. Prüfen Sie auf der Secret Manager-Seite des Projekts, in dem Sie den Agenten bereitstellen, ob alle in secret_env referenzierten SECRET_ID und VERSION_ID vorhanden sind und den Status Aktiviert haben.
    2. Wenn eine referenzierte Version deaktiviert oder gelöscht wurde, aktivieren Sie eine gültige Version oder aktualisieren Sie secret_env, um auf eine aktivierte Version zu verweisen.
  • Für PERMISSION_DENIED: Weisen Sie dem Dienstkonto, das das Secret abruft, die Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das Secret (oder das Projekt, das das Secret enthält) zu:
    • Standarddienstkonto: Gewähren Sie dem AI Platform Reasoning Engine-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) die Rolle.
    • Benutzerdefiniertes Dienstkonto: Weisen Sie die Rolle dem benutzerdefinierten Dienstkonto zu, das für den Agent konfiguriert ist.

Fehler bei der Bindung des KI-Agenten-Gateways

Wenn Sie Traffic über Agent Gateway weiterleiten und die Bereitstellung oder Aktualisierung Ihres KI-Agenten fehlschlägt, bevor der KI-Agent gestartet wird, kann eines der folgenden Probleme die Ursache sein:

Zeitüberschreitung bei der Bindung des KI-Agenten-Gateways

Problem:

Die Bereitstellung oder Aktualisierung eines Agents schlägt mit dem Status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT) und einer Meldung wie der folgenden fehl:

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.

Mögliche Ursachen:

Agent Runtime-Agenten im selben Projekt und in derselben Region teilen sich eine Bindung an jedes konfigurierte Agent Gateway. Das Einrichten oder Löschen der freigegebenen Bindung kann mehrere Minuten länger dauern als das Anhängen eines Agenten an eine aktive Bindung. Das Deployment oder Update wird abgebrochen, wenn ein anderer Bindungs- oder Aufhebungsvorgang im selben Projekt und in derselben Region nicht innerhalb der zulässigen Zeit abgeschlossen wird. Häufige Ursachen:

  • Gleichzeitige Erstbindungen: Sie binden mehrere KI-Agenten an ein Agent Gateway im selben Projekt und in derselben Region, bevor die erste gemeinsame Einrichtung abgeschlossen ist.
  • Aufhebung der Bindung wird ausgeführt: Sie heben die Bindung des letzten an das Gateway gebundenen KI-Agenten im Projekt und in der Region auf oder löschen ihn und binden dann einen anderen KI-Agenten an dasselbe oder ein anderes Gateway, bevor der gemeinsame Abbau abgeschlossen ist.
  • Wiederholen nach einer fehlgeschlagenen Bindung: Eine Bereitstellung oder ein Update, bei dem ein Gateway gebunden wird, schlägt fehl und Sie versuchen es noch einmal, bevor die Agent Runtime die Bereinigung der fehlgeschlagenen Einrichtung abgeschlossen hat.

Empfohlene Lösungen:

  • Warten Sie einige Minuten, bis andere Vorgänge auf dem im Fehler genannten Gateway abgeschlossen sind, und versuchen Sie dann noch einmal, die Bereitstellung oder Aktualisierung durchzuführen.
  • Wenn Sie mehrere KI-Agenten in einem Projekt und einer Region ohne aktive Agent Gateway-Bindung binden möchten, binden Sie zuerst einen KI-Agenten und warten Sie, bis dieser Vorgang erfolgreich abgeschlossen ist. Stellen Sie dann die verbleibenden Agents gleichzeitig bereit oder aktualisieren Sie sie.
  • Vermeiden Sie in automatisierten Workflows, die Bindung des letzten an ein Gateway gebundenen KI-Agenten in einem Projekt und einer Region aufzuheben oder ihn zu löschen, unmittelbar bevor Sie andere KI-Agenten binden. Wenn Sie den letzten an das Gateway gebundenen Agent entfernen, wird die freigegebene Bindung aufgehoben. Bei der nächsten Bereitstellung wird die vollständige Einrichtung wiederholt.

Nicht zutreffende Lösungen:

  • In den Containerlogs oder den Agent Gateway-Traffic-Logs wird für diesen Fehler kein Fehler angezeigt, da die Zeitüberschreitung auftritt, bevor Agent Runtime den Container Ihres KI-Agenten startet.
  • Wenn Sie den Code, die requirements oder die resource_limits Ihres Agenten ändern, wird die Einrichtungszeit für die gemeinsame Bindung nicht verkürzt.

Wenn die Gateway-Bindung erfolgreich ist, der Container aber nicht gestartet werden kann, finden Sie weitere Informationen unter Fehler beim Start der Agent Runtime.

Bindung des KI-Agenten-Gateways abgebrochen

Problem:

Die Bereitstellung oder Aktualisierung eines KI-Agenten schlägt mit dem Status 409, ABORTED (REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED) und einer Meldung wie der folgenden fehl:

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.

Mögliche Ursache:

Agent Runtime-Agenten im selben Projekt und in derselben Region teilen sich eine Bindung an jedes konfigurierte Agent Gateway. Wenn Sie mehrere Agents an dasselbe Gateway binden, bevor die gemeinsame Bindung eingerichtet ist, wird die Bindung durch eine Bereitstellung oder Aktualisierung eingerichtet und die anderen warten darauf. Wenn diese Bereitstellung oder Aktualisierung fehlschlägt, bevor die Bindung bereit ist, setzt Agent Runtime die Bindung zurück und jede Bereitstellung oder Aktualisierung, die darauf gewartet hat, schlägt mit diesem Fehler fehl. Die Bereitstellung oder Aktualisierung, mit der die Bindung eingerichtet wurde, meldet einen eigenen Fehler, der möglicherweise nicht mit dem Agent Gateway zusammenhängt.

Empfohlene Lösungen:

  • Warten Sie mindestens 10 Minuten, bis die Agent Runtime das fehlgeschlagene Setup zurückgesetzt hat, und versuchen Sie dann noch einmal, die Bereitstellung oder Aktualisierung durchzuführen. Ein Wiederholungsversuch, der vor dem Abschluss des Rollbacks gestartet wird, kann mit dem Status 504, DEADLINE_EXCEEDED fehlschlagen. Siehe Zeitüberschreitung bei der Bindung des KI-Agenten-Gateways.
  • Wenn Sie mehrere Bereitstellungen oder Aktualisierungen wiederholen möchten, wiederholen Sie zuerst eine und warten Sie, bis dieser Vorgang erfolgreich abgeschlossen wurde. Wiederholen Sie dann die restlichen Bereitstellungen oder Aktualisierungen gleichzeitig. Wenn der erste Vorgang fehlschlägt, wird der zugrunde liegende Fehler anstelle von 409, ABORTED zurückgegeben (z. B. Agent Gateway-Bindung vorübergehend nicht verfügbar oder Container-Image-Build fehlgeschlagen). Sie können den Fehler im Fehlerkatalog nachschlagen.

Nicht zutreffende Lösungen:

  • In den Containerlogs oder den Trafficlogs des Agent Gateway wird für diesen Fehler kein Fehler angezeigt, da der Fehler auftritt, bevor die Agent Runtime den Container Ihres Agents startet.
  • Das Ändern des Codes, der requirements oder der resource_limits Ihres KI-Agenten hilft nicht, da dieser Fehler durch eine andere Bereitstellung oder ein anderes Update verursacht wurde, nicht durch Ihren KI-Agenten.

Agent-Gateway-Bindung vorübergehend nicht verfügbar

Problem:

Die Bereitstellung oder Aktualisierung eines Agents schlägt mit dem Status 503, UNAVAILABLE (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE) und einer Meldung wie der folgenden fehl:

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.

Mögliche Ursache:

Wenn der erste Agent in einem Projekt und einer Region an ein Agent Gateway gebunden wird, richtet Agent Runtime freigegebene, von Google verwaltete Netzwerkressourcen ein, die Agents mit dem Gateway verbinden. Wenn ein Google Cloud-Dienst, von dem diese Einrichtung abhängt, nach mehreren automatischen Wiederholungsversuchen weiterhin temporäre Fehler zurückgibt, setzt Agent Runtime die Einrichtung zurück und die Bereitstellung oder Aktualisierung schlägt mit diesem Fehler fehl. Andere Bereitstellungen oder Updates, die auf dieselbe Einrichtung gewartet haben, schlagen mit dem Status 409, ABORTED fehl. Weitere Informationen finden Sie unter Agent Gateway-Bindung abgebrochen.

Empfohlene Lösungen:

  • Warten Sie mindestens 10 Minuten, bis die Agent Runtime das fehlgeschlagene Setup zurückgesetzt hat, und versuchen Sie dann noch einmal, die Bereitstellung oder Aktualisierung durchzuführen. Ein Wiederholungsversuch, der vor dem Abschluss des Rollbacks gestartet wird, kann mit dem Status 504, DEADLINE_EXCEEDED fehlschlagen. Siehe Zeitüberschreitung bei der Bindung des KI-Agenten-Gateways.
  • Wenn der Fehler nach mehreren Wiederholungsversuchen weiterhin auftritt, wenden Sie sich an den Support und geben Sie den Namen des fehlgeschlagenen Vorgangs im Format projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID an.

Nicht zutreffende Lösungen:

  • Das Ändern des Codes, der requirements oder der resource_limits Ihres KI-Agenten hilft nicht, da der Fehler auftritt, bevor die Agent Runtime Ihren KI-Agenten bereitstellt.
  • Eine Kontingenterhöhung für Ihr Projekt hat keine Auswirkungen, da Google diese Netzwerkressourcen verwaltet.

Supportressourcen

Wenn das Problem weiterhin besteht, findest du in unserem Supportleitfaden weitere Informationen.