Zum Hauptinhalt springen
Ein fehlgeschlagener Lauf wirft einen Fehler aus dem Run- oder Continue-Aufruf oder gibt ihn zurück. Eine Pause (waiting_for_human) oder eine Stoppbedingung (stopped) ist kein Fehler: Beide geben ein normales Ergebnis zurück. Welche Fehler zusätzlich ein run.failed-Event senden, unterscheidet sich je nach Sprache. Verlass dich daher nicht allein auf das Event, um einen Fehler zu erkennen.

Wie ein fehlgeschlagener Lauf sichtbar wird

Welche Events bei einem Fehler ausgelöst werden

Unter Lifecycle-Hooks ist jedes Event aufgeführt.

Die Ursache eines Fehlers finden

Fehlertypen in TypeScript

AgentGatewayError hat status, statusText, headers, body, requestId, generationId, reason, errorType, errorOrigin, failedProviders, failedStatuses und Routing-Diagnosen. Fehlgeschlagene Läufe und Schritte behalten dieselben Details in errorDetails. Ein Fehler mitten in einer gestreamten Antwort ist ein AgentStreamError, eine Unterklasse mit code und retryable. AgentSchemaValidationError hat ein target mit tool_input, tool_output, tool_event oder agent_output sowie details mit dem Fehler des Validators. Behandle diese als Vertragsfehler, nicht als vorübergehende Modellfehler. Um einen beliebigen Fehler einzuordnen, zum Beispiel in modelRetry.retryOn, verwendest du agentErrorIsRetryable(error), agentRetryAfterMs(error) und agentErrorIsContextOverflow(error).

Fehlertyp in Rust

Jeder Laufzeitfehler ist ein AgentError; lies ihn mit message(). Gateway-Werte vom Typ PhaseoError werden in AgentError umgewandelt. Wenn du den ursprünglichen Gateway-Status und -Body brauchst, rufe den Client phaseo direkt auf oder implementiere einen eigenen ModelClient, der sie behält.

Tool-Fehler abfangen

Standardmäßig lässt ein Tool-Fehler den Lauf fehlschlagen. Setze die Fehlerrichtlinie des Tools auf return-to-model, wenn das Modell sinnvoll etwas anderes versuchen kann: Der Fehler wird zum Tool-Ergebnis {"error": "..."}, und der Lauf geht weiter. Behalte den Standard fail-run für unsichere oder nicht behebbare Fehler bei.

Abbrüche und Timeouts behandeln

Ein Tool-Timeout oder ein Abbruch stoppt nicht immer die Arbeit des Tools selbst. Gib HTTP-, Datenbank- und Prozessaufrufen innerhalb von Tools eigene Fristen und behandle einen abgebrochenen oder abgelaufenen Lauf als beendet, sofern deine Anwendung keinen neuen startet.

Einen unterbrochenen TypeScript-Lauf wiederherstellen

Wenn ein Lauf mitten in einem Schritt abgestürzt ist oder abgebrochen wurde, kann sein Verlauf Tool-Aufrufe ohne Ergebnisse enthalten, die Anbieter ablehnen. continueRun() in TypeScript beantwortet sie als nicht ausgeführt und sendet history.repaired. Rufe repairToolHistory(messages) selbst auf, wenn du die Nachrichten anderswo wiederverwendest.

Zuerst das hier prüfen

  • PHASEO_API_KEY erreicht den Prozess und wird an den Gateway-Client übergeben.
  • Jedes Tool hat eine eindeutige, stabile ID.
  • Freigaben, Ablehnungen und Tool-Ausgaben verwenden exakte Tool-Call-IDs, und eine menschliche Eingabenachricht ersetzt nie eine Tool-Ausgabe.
  • Das gesamte Laufergebnis wird gespeichert, bevor du eine Freigabe-Oberfläche anzeigst oder die Kontrolle an eine andere Anfrage oder einen anderen Worker übergibst.
  • Validatoren sind deterministisch und frei von Nebeneffekten, sodass eine fehlgeschlagene Prüfung sicher wiederholt werden kann.
  • Modellwiederholungen sind begrenzt; Validierungs- und Freigabefehler sollten nicht blind wiederholt werden.
Um zu sehen, welcher Schritt fehlgeschlagen ist, zeichne step.started, model.requested und tool.failed mit Lifecycle-Hooks auf, und unter Beobachtbarkeit findest du die IDs, die einen Schritt mit den Gateway-Logs verknüpfen.
Zuletzt geändert am 5. November 2026