In diesem Dokument wird beschrieben, wie Sie Fehler beheben können, die bei der Verwendung eines KI-Agenten auftreten können.
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.
Vorgangsschemas sind leer
Wenn Ihr Agent eine leere Liste von .operation_schemas() zurückgibt, kann dies an einem der folgenden Probleme liegen:
Fehler beim Generieren eines Schemas während der Erstellung des KI-Agenten
Problem:
Wenn Sie den Agent bereitstellen, erhalten Sie eine Warnung ähnlich der folgenden:
WARNING:vertexai.agent_engines:failed to generate schema: issubclass() arg 1 must be a class
Mögliche Ursache:
Diese Warnung kann auftreten, wenn Sie einen Agent mit der vordefinierten Vorlage LangchainAgent in einer Version von google-cloud-aiplatform bereitstellen, die älter als 1.49.0 ist. Führen Sie folgenden Befehl im Terminal aus, um zu prüfen, welche Version Sie verwenden:
pip show google-cloud-aiplatformEmpfohlene Lösung:
Führen Sie in Ihrem Terminal den folgenden Befehl aus, um das google-cloud-aiplatform-Paket zu aktualisieren:
pip install google-cloud-aiplatform --upgradeFühren Sie nach dem Aktualisieren des google-cloud-aiplatform-Pakets den folgenden Befehl aus, um zu prüfen, ob die Version 1.49.0 oder höher ist:
pip show google-cloud-aiplatformWenn Sie sich in einer Notebookinstanz befinden (z. B. Jupyter, Colab oder Workbench), müssen Sie möglicherweise Ihre Laufzeit neu starten, um das aktualisierte Paket verwenden zu können. Nachdem Sie überprüft haben, dass Ihre Version von google-cloud-aiplatform 1.49.0 oder höher ist, versuchen Sie noch einmal, Ihren Agenten bereitzustellen.
PermissionDenied-Fehler beim Abfragen des KI-Agenten
Ihre Abfrage schlägt möglicherweise fehl, wenn Sie nicht die erforderlichen Berechtigungen haben.
Berechtigungen für Agent Platform-Erweiterungen
Vorgang
Möglicherweise erhalten Sie einen PermissionDenied-Fehler, der in etwa so aussieht:
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}"
}
]
Ihr Agent hat nicht die Berechtigungen für Agent Platform-Erweiterungen. Wenn Sie Agent Platform-Erweiterungen mit Agent Runtime verwenden möchten, weisen Sie dem Dienstkonto Ihrer Agentenidentität die Rolle „Agent Platform User“ (roles/aiplatform.user) zu.
Weitere Informationen finden Sie unter Identität und Berechtigungen für Ihren Agenten einrichten.
LLM-Berechtigungen
Problem:
Möglicherweise erhalten Sie einen PermissionDenied-Fehler, der in etwa so aussieht:
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}"
}
]
Mögliche Ursache:
Ihr Dienstkonto für die Agentenidentität hat möglicherweise nicht die erforderlichen Berechtigungen, um Ihr Large Language Model (LLM) abzufragen.
Empfohlene Lösung:
Prüfen Sie, ob Ihr Dienstkonto die in der Fehlermeldung aufgeführten IAM-Berechtigungen (Identity and Access Management) hat. Ein Beispiel für eine IAM-Berechtigung, die Ihnen möglicherweise fehlt, ist aiplatform.endpoints.predict. Weitere Informationen finden Sie unter Identität und Berechtigungen für den Agent einrichten.
Anfrage wird abgelehnt, bevor sie Ihren KI-Agenten erreicht
Wenn Ihre Anfrage fehlschlägt, bevor sie von der Agent Runtime an Ihren KI-Agenten gesendet wird, kann dies einen der folgenden Gründe haben:
KI-Agent nicht gefunden
Problem:
Die Anfrage schlägt mit dem Status 404, NOT_FOUND (REASONING_ENGINE_NOT_FOUND) und einer Meldung wie der folgenden fehl:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` was not found.
Mögliche Ursachen:
- Die Projekt-, Standort- oder Ressourcen-ID in der Anfrage ist falsch.
- Der KI-Agent wurde gelöscht.
Empfohlene Lösungen:
- Vergleichen Sie den Ressourcennamen in der Fehlermeldung mit Ihren bereitgestellten Agenten. Siehe Bereitgestellte Agents auflisten.
- Achten Sie darauf, dass Ihr Client die Anfrage an das Projekt und die Region sendet, in der Sie den KI-Agenten bereitgestellt haben.
KI-Agent ist nicht aktiv
Problem:
Die Anfrage schlägt mit dem Status 403, PERMISSION_DENIED (REASONING_ENGINE_NOT_ACTIVE) und einer Meldung wie der folgenden fehl:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` is not active, so it can't serve requests.
Mögliche Ursachen:
- Der KI-Agent wird noch erstellt.
- Der KI-Agent konnte nicht erstellt werden.
- Der KI-Agent wird gelöscht.
Empfohlene Lösungen:
- Wenn Sie den Agenten gerade erst erstellt haben, warten Sie, bis die Erstellung abgeschlossen ist, und versuchen Sie es dann noch einmal.
- Wenn die Erstellung des KI-Agenten fehlgeschlagen ist, prüfen Sie die Logs, die im Feld
logs_urlder Fehlermetadaten verlinkt sind, um die Ursache zu finden. Beheben Sie den Fehler und stellen Sie den Agenten noch einmal bereit. Siehe Fehlerbehebung bei der Bereitstellung eines Agents.
Der Agent hat keine laufenden Instanzen
Problem:
Die Anfrage schlägt mit dem Status 400, FAILED_PRECONDITION (REASONING_ENGINE_NO_RUNNING_INSTANCES) und einer Meldung wie der folgenden fehl:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` has no running instances because no agent is deployed to it.
Mögliche Ursache:
Die Ressource ist vorhanden, aber beim Erstellen oder Aktualisieren wurde kein Agent (Objekt, Quelldateien oder Container-Image) für die Bereitstellung angegeben.
Empfohlene Lösung:
Aktualisieren Sie die Ressource mit einem bereitzustellenden Agenten. Weitere Informationen finden Sie unter Bereitgestellten Agent aktualisieren.
A2A-Methoden nicht definiert
Problem:
Eine A2A-Anfrage schlägt mit dem Status 400, FAILED_PRECONDITION (REASONING_ENGINE_A2A_NOT_CONFIGURED) und einer Meldung ähnlich der folgenden fehl:
The Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` does not define A2A methods, so it can't serve A2A requests.
Mögliche Ursache:
Sie haben eine A2A-Anfrage, z. B. eine Anfrage für die Agentenkarte oder eine Nachricht, an einen Agenten gesendet, der nicht als A2A-Agent erstellt wurde.
Empfohlene Lösungen:
- Stellen Sie einen A2A-Agenten bereit, um A2A-Anfragen zu verarbeiten. Weitere Informationen finden Sie unter A2A-Agent erstellen.
- Informationen zum Abfragen eines KI-Agenten, der kein A2A-Agent ist, finden Sie unter KI-Agenten verwenden.
Anfrage-Nutzlast ist zu groß
Problem:
Die Anfrage schlägt mit dem Status 400, FAILED_PRECONDITION (REASONING_ENGINE_REQUEST_TOO_LARGE) oder einem HTTP-413 Request Entity Too Large-Fehler und einer Meldung wie der folgenden fehl:
The request to the Reasoning Engine `projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID` exceeds the 32 MiB maximum HTTP payload size (about 24 MiB for Base64-encoded files).
Mögliche Ursachen:
- Die Agent Runtime erzwingt eine feste maximale HTTP-Anfragetextgröße von 32 MiB.
- Inline-Dateianhänge, die in JSON Base64-codiert sind, werden um etwa 33 % vergrößert. Dateien, die größer als etwa 24 MiB sind, überschreiten daher das Nutzlastlimit von 32 MiB.
- In mehrstufigen Unterhaltungen überschreiten der akkumulierte Unterhaltungsverlauf und die zuvor in der Nutzlast der Anfrage gesendeten Anhänge die Gesamtgröße des Anfragetexts von 32 MiB.
Empfohlene Lösungen:
- Laden Sie große Dateien in Cloud Storage hoch und übergeben Sie in Ihrer Anfrage
gs://-URIs anstelle von Inline-Base64-codierten Byte. - Komprimieren, teilen oder verkleinern Sie große Anhänge, bevor Sie sie senden, damit der gesamte serialisierte HTTP-Anfragetext unter 32 MiB (etwa 24 MiB Rohdateien) bleibt.
- Starten Sie eine neue Unterhaltung oder entfernen Sie frühere Anhänge aus dem Unterhaltungsverlauf, wenn der Multi-Turn-Kontext sich dem Limit nähert.
Ausführung der Reasoning Engine fehlgeschlagen
Wenn Sie beim Abfragen Ihres Agenten die Fehlermeldung „Reasoning Engine Execution failed“ erhalten, kann dies an einem der in diesem Abschnitt beschriebenen Probleme liegen.
Ungültige Eingaben für .query()
Problem:
Möglicherweise erhalten Sie einen FailedPrecondition-Fehler, der in etwa so aussieht:
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"Invalid request: `{'query': ...}`"}
Mögliche Ursache:
Dieser Fehler tritt auf, wenn Sie die Eingaben für die Abfrage als Positionsargumente anstelle von Schlüsselwortargumenten angeben. Sie rufen beispielsweise agent.query(query_str) anstelle von agent.query(input=query_str) auf.
Empfohlene Lösung:
Wenn Sie eine Instanz einer bereitgestellten Reasoning Engine abfragen, geben Sie alle Eingaben als Schlüsselwortargumente an.
Gemini-Modellkontingent aufgebraucht
Problem:
Möglicherweise erhalten Sie einen Fehler, der einem der folgenden ähnelt und darauf hinweist, dass der Fehler durch den Aufruf von Gemini ausgelöst wurde:
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."}
oder eine andere Fehlermeldung:
FailedPrecondition: 400 Reasoning Engine Execution failed. Error Details:
{"detail":"...langchain_google_vertexai/chat_models.py...google.api_core.exceptions.InternalServerError: 500 Internal error occurred."}
Mögliche Ursache:
Das kann passieren, wenn Sie in letzter Zeit zu viele Anfragen gesendet und das Kontingent für das Gemini-Modell aufgebraucht haben.
Empfohlene Lösung:
Folgen Sie dem Prozess zur Kontingentverwaltung für Gemini-Modelle, um das Kontingent zu erhöhen. Alternativ können Sie Ihre Tests einer Ratenbegrenzung unterziehen und es später noch einmal versuchen.
Falsche Reasoning Engine-ID
Problem:
Möglicherweise erhalten Sie die Fehlermeldung, dass die Ausführung der Reasoning Engine mit dem Detail Not Found fehlgeschlagen ist.
Mögliche Ursache:
Dieser Fehler kann auftreten, wenn Sie beim Abfragen Ihres KI-Agenten eine falsche Reasoning Engine-ID verwenden.
Empfohlene Lösung:
Prüfen Sie, ob Sie die richtige Reasoning Engine-ID für Ihren Agenten verwenden.
Supportressourcen
Wenn das Problem weiterhin besteht, findest du in unserem Supportleitfaden weitere Informationen.