Tool Failure: Wenn Agent-Tools ausfallen

Problem

Die Anfrage wirkt Standard: Zahlung prüfen und den Bestellstatus bestätigen.

In den Traces sieht man etwas anderes: In 9 Minuten hat ein Run 29 Tool-Aufrufe gemacht (billing.get_invoice - 18, payments.verify - 11), die meisten endeten mit timeout oder 5xx. Für diese Aufgabenklasse kann das etwa ~$2.50 statt der üblichen ~$0.12 kosten.

Der Service ist formal nicht "tot": ein Teil der Aufrufe liefert 200. Aber der User bekommt keine finale Antwort, und Run-Backlog sowie Latenz steigen.

Das System crasht nicht.

Es bleibt zwischen Tool-Fehlern und Retries stecken und akkumuliert langsam Latenz und Run-Backlog.

Analogie: Stell dir einen Kurier vor, der an ein geschlossenes Lager fährt, nochmal anruft, wartet, wieder anruft und immer wieder zur selben Tür zurückkehrt. Er ist ständig "in progress", aber die Bestellung bewegt sich nicht. Tool Failure bei Agenten sieht genauso aus: Aktionen ja, Ergebnis nein.

Warum das passiert

Tool Failure entsteht nicht nur durch ein instabiles API.

Meist liegt das Kernproblem darin, dass die Runtime keine klare Strategie hat, Tool-Fehler zu klassifizieren und zu behandeln.

In Production sieht das meist so aus:

1. ein externer Service liefert timeout, 5xx oder instabiles Payload;
2. Runtime oder Tool-Gateway wiederholt den Aufruf ohne klare Fehlerklassifikation;
3. non-retryable Fehler geraten ebenfalls in Retry-Loops;
4. ohne Circuit Breaker und Fallback hängt der Run oder verbrennt Budget.

Das Problem ist nicht ein einzelner zufälliger API-Fehler. Das Problem ist, dass das System die Fehlerwelle nicht stoppt, bevor sie zum Incident wird.

Diese Incident-Klasse nennt man meist agent tool failure - wenn ein Agent-System wegen Instabilität oder Fehlern externer Tools nicht zuverlässig laufen kann.

Welche Ausfälle am häufigsten auftreten

Um es praktisch zu halten: In Production sieht man meist vier Tool-Failure-Pattern.

Transient failures

Das Tool liefert gelegentlich 408/429/5xx. Bei schwacher Retry-Kontrolle wird ein kurzer Ausfall zum Retry Storm.

Typische Ursache: fehlendes backoff+jitter und fehlendes Retry-Budget.

Wrong retry classification

401, 403, 404, 409, schema validation errors oder policy denials landen in Retries, obwohl sie sofort beendet werden sollten.

Typische Ursache: retryable und non-retryable sind nicht an einer Stelle getrennt.

Tool contract drift

Das Tool ändert Antwortformat oder Fehlerstruktur. Der Agent kann das Ergebnis nicht stabil interpretieren und "fragt" denselben Service erneut.

Typische Ursache: kein Contract-Versioning und keine Payload-Validierung im Gateway.

Cascading failure

Ein problematisches Tool erhöht die Latenz des Gesamtsystems: Worker warten, Queue wächst, andere Runs werden ebenfalls langsamer.

Typische Ursache: fehlender Circuit Breaker und Fallback für degraded dependencies.

Wie man diese Probleme erkennt

Tool Failure ist über die Kombination von Runtime- und Gateway-Metriken gut sichtbar.

Wie man Tool Failure von Logikfehlern des Agenten unterscheidet

Nicht jeder Run-Fehler bedeutet, dass der Agent "schlecht denkt". Das Schlüsselkriterium: wo genau der Loop bricht.

Normal, wenn:

• der Fehler in einem einzelnen externen Tool lokalisiert ist;
• stop reason direkt auf die Abhängigkeit zeigt (tool_timeout, tool_5xx, circuit_open);
• der User nach Fallback ein partielles, aber korrektes Ergebnis bekommt.

Gefährlich, wenn:

• der Agent non-retryable Fehler wie retryable wiederholt;
• klare stop reasons auf Tool-Gateway-Ebene fehlen;
• ein Tool-Fehler den ganzen Workflow mitzieht.

Wie man solche Ausfälle stoppt

Praktisch sieht das so aus:

1. Tool-Fehler in retryable und non-retryable klassifizieren;
2. Retry-Policy in einem Tool-Gateway halten (backoff+jitter + budget);
3. Circuit Breaker gegen Fehlerwellen einsetzen;
4. bei Tool-Ausfall fallback/partial Ergebnis und stop reason zurückgeben.

Minimaler Guard für Tool-Fehler:

from dataclasses import dataclass
import time


RETRYABLE = {408, 429, 500, 502, 503, 504}
NON_RETRYABLE = {400, 401, 403, 404, 409, 422}


@dataclass(frozen=True)
class ToolFailureLimits:
    max_retry: int = 2
    open_circuit_after: int = 3
    circuit_cooldown_s: int = 20


class ToolFailureGuard:
    def __init__(self, limits: ToolFailureLimits = ToolFailureLimits()):
        self.limits = limits
        self.fail_streak = 0
        self.circuit_open_until = 0.0

    def before_call(self) -> str | None:
        if time.time() < self.circuit_open_until:
            return "tool_unavailable:circuit_open"
        return None

    def on_result(self, status_code: int, attempt: int) -> str | None:
        if status_code in NON_RETRYABLE:
            self.fail_streak = 0
            return "tool_failure:non_retryable"

        if status_code in RETRYABLE:
            self.fail_streak += 1
            if self.fail_streak >= self.limits.open_circuit_after:
                self.circuit_open_until = time.time() + self.limits.circuit_cooldown_s
                return "tool_unavailable:circuit_open"
            if attempt >= self.limits.max_retry:
                return "tool_failure:retry_exhausted"
            return "tool_retry:allowed"

        self.fail_streak = 0
        return None

Das ist ein Basis-Guard. In Production ergänzt man ihn meist mit per-tool limits und exponentiellem backoff mit jitter. attempt ist hier in der Regel 1-based (1, 2, 3...), und der Guard-State wird meist pro Tool oder pro Run gehalten.

Wo das in der Architektur umgesetzt wird

In Production ist Tool-Failure-Kontrolle fast immer auf drei Systemschichten verteilt.

Tool Execution Layer ist der zentrale Kontrollpunkt: Args- und Payload-Validierung, Retry-Policy, Fehlerklassifikation, Circuit Breaker. Wenn diese Schicht schwach ist, wird selbst ein einfaches API-Problem schnell zur Cascade.

Agent Runtime steuert den Run-Lifecycle: stop reasons, timeout, kontrolliertes Beenden und Fallback-Antwort. Hier ist entscheidend, Runs nicht um jeden Preis fortzusetzen.

Policy Boundaries definiert, welche Tools erlaubt sind und wann ein Run fail-closed enden muss. Das ist besonders wichtig für Write-Tools und Permission-Fehler.

Checkliste

Bevor du einen Agenten in Production shipst:

• [ ] retryable/non-retryable Fehler sind klar getrennt;
• [ ] Retries sind in einem Gateway umgesetzt, nicht in mehreren Schichten;
• [ ] max_retry, backoff+jitter und Retry-Budget sind gesetzt;
• [ ] Circuit Breaker und Cooldown sind für jedes kritische Tool konfiguriert;
• [ ] stop reasons decken timeout, 5xx, non_retryable, circuit_open ab;
• [ ] fallback/partial Antwort ist vor dem Incident definiert;
• [ ] Alerts auf tool_error_rate, retry_attempts_per_call, queue_backlog;
• [ ] Runbook für degraded mode und Dependency-Rollback ist vorhanden.

FAQ

Q: Reicht es, nur den Timeout für ein problematisches Tool zu erhöhen?
A: Nein. Das maskiert oft nur das Problem und erhöht die Latenz. Du brauchst error classification, Retry-Budget und Circuit Breaker.

Q: Wo sollten Retries leben?
A: In einem einzigen choke point, meist im Tool-Gateway. Retries in mehreren Schichten erzeugen fast immer amplification.

Q: Welche Fehler sind üblicherweise non-retryable?
A: 401, 403, 404, 409, 422, schema validation errors und policy denials. Solche Runs sollte man meist sofort mit klarem stop reason beenden.

Q: Was sollte der User sehen, wenn ein Tool nicht verfügbar ist?
A: Den Stoppgrund, was bereits geprüft wurde, und den sicheren nächsten Schritt: fallback, partial Ergebnis oder manuelle Eskalation.

Tool Failure sieht fast nie wie ein einzelner großer Ausfall aus. Meist ist es eine Serie kleiner Fehler, die sich in Retry-Loops und Queue aufbauen. Darum brauchen Production-Agenten nicht nur Tools, sondern strikte Ausführungsdisziplin.

Verwandte Seiten

Wenn dieses Problem in Production auftritt, ist auch Folgendes hilfreich:

• Warum AI-Agenten scheitern - allgemeine Karte von Ausfällen in Production.
• Tool spam - wie Wiederholungsaufrufe Tool-Fehler zu Incidents machen.
• Partial outage - wie partielle Degradation von Abhängigkeiten Workflows bricht.
• Budget explosion - wie Retry Storms Kosten still aufblasen.
• Agent Runtime - wo stop reasons und Run-Lifecycle gesteuert werden.
• Tool Execution Layer - wo Retries, Validierung und Circuit Breaker liegen.