Warum KI-Agenten in der Produktion versagen: Teststrategien für jeden Ausfallmodus

Ihr Agent funktionierte in der Demo: Er las ein Ticket, rief drei APIs auf und veröffentlichte eine saubere Zusammenfassung. Nach dem Release schickte er demselben Kunden doppelte E-Mails, verbrauchte ein Tagesbudget durch eine Wiederholungsschleife und lieferte dem Frontend eine nicht parsebare Nutzlast.

Apidog noch heute ausprobieren

Die Lücke zwischen einem funktionierenden Prototyp und einem zuverlässigen Agenten entsteht meist nicht im Modell. Sie entsteht in der API-Schicht: Tool-Aufrufe können fehlschlagen, gedrosselt werden, Timeouts erzeugen oder unerwartete Antworten liefern. Ein Agent ist letztlich eine Schleife aus Tool-Aufrufen — und jeder Tool-Aufruf ist eine HTTP-Anfrage.

Die gute Nachricht: Diese Zuverlässigkeit ist testbar. Sie müssen nicht darauf vertrauen, dass sich das Modell korrekt verhält. Stattdessen simulieren Sie Fehlerpfade gezielt, bevor Benutzer sie in Produktion auslösen. Dieser Leitfaden zeigt fünf typische Fehlermodi und eine praktische Teststruktur dafür. Apidog hilft dabei, API-Verträge zu definieren, Abhängigkeiten zu simulieren und Antworten zu validieren.

Agenten scheitern an der API-Grenze, nicht am Prompt

Wenn ein Agent in Produktion fehlerhaft arbeitet, wird oft zuerst der Prompt angepasst. Das kann helfen, ist aber häufig nicht die Ursache.

Typischer Ablauf eines Agentenschritts:

1. Das Modell wählt ein Tool.
2. Ihr Code übersetzt die Tool-Wahl in eine HTTP-Anfrage.
3. Ein externer Dienst antwortet.
4. Ihr Code gibt das Ergebnis an das Modell zurück.

Drei dieser vier Schritte sind klassische API-Integration. Die Antwort eines Upstream-Dienstes kann langsam, fehlerhaft, ratenbegrenzt oder strukturell anders als erwartet sein. Das Modell verarbeitet diese Eingabe trotzdem und kann daraus eine zuversichtliche, aber falsche Aktion ableiten.

Die zentrale Frage lautet daher nicht: „Ist das Modell intelligent genug?“

Sondern: „Habe ich jede realistische Fehlerart in den API-Aufrufen meines Agenten getestet?“

Fehlermodus 1: Tool-Aufrufe verletzen den Vertrag

Der häufigste Fehler: Der vom Modell erzeugte Tool-Aufruf passt nicht zum API-Vertrag.

Beispiele:

• Ein Pflichtfeld fehlt.
• Das Modell erfindet einen Parameter.
• Ein Typ ist falsch.
• Ein Enum-Wert ist ungültig.
• Der Endpunkt ist korrekt, aber die Argumente ergeben fachlich keinen Sinn.

Ein Buchungsagent könnte beispielsweise Folgendes erzeugen:

{
  "guests": "two"
}

Die API erwartet jedoch:

{
  "guests": 2
}

Ein sauberer API-Vertrag sollte diesen Request ablehnen. Problematisch wird es, wenn die API zwar 200 OK liefert, aber einen Fehler im Response-Body versteckt — und der Agent den Vorgang trotzdem als Erfolg interpretiert.

So testen Sie Tool-Verträge

1. Definieren Sie für jedes Tool ein Request-Schema.
2. Validieren Sie jeden ausgehenden Tool-Aufruf gegen dieses Schema.
3. Lassen Sie den Test bei Vertragsverletzungen sofort fehlschlagen.
4. Prüfen Sie zusätzlich, ob der Agent einen Validierungsfehler korrekt behandelt.

Beispiel für ein JSON-Schema:

{
  "type": "object",
  "required": ["guests", "date"],
  "properties": {
    "guests": {
      "type": "integer",
      "minimum": 1
    },
    "date": {
      "type": "string",
      "format": "date"
    }
  },
  "additionalProperties": false
}

Der Leitfaden zum Testen von Tool-Aufrufen eines KI-Agenten beschreibt diesen Ansatz detaillierter. Für den vollständigen Ablauf von der Definition bis zur Ausführung siehe auch Testen von Agenten, die Ihre APIs aufrufen.

Praktisch: Importieren Sie Ihre Tool-Schemata in Apidog und führen Sie reale Agenten-Requests gegen diese Definitionen aus. Bei Abweichungen erhalten Sie einen Validierungsfehler, der das konkrete fehlerhafte Feld benennt.

Fehlermodus 2: Upstream-Fehler und Ratenbegrenzungen

Jede externe Abhängigkeit kann fehlschlagen:

• 429 Too Many Requests
• 500 Internal Server Error
• Timeout
• ungültiger oder unvollständiger Response-Body
• Verbindungsabbruch

Ein robuster Agent behandelt diese Fälle mit begrenzten Wiederholungsversuchen und Backoff. Ein fragiler Agent gibt entweder sofort auf oder wiederholt den Aufruf aggressiv, bis er weitere Drosselung auslöst und Budget verbrennt.

Die Häufigkeit dieses Problems zeigt sich auch an Diskussionen über Muster für die Fehlerbehebung von Agenten.

Testen Sie Fehler als Sequenz, nicht nur einzeln

Ein einzelner Mock-Fehler reicht oft nicht. Simulieren Sie eine realistische Abfolge:

1. 429 mit Retry-After
2. 500
3. erfolgreicher Response

Beispiel:

Request 1 -> 429 Too Many Requests
Retry-After: 2

Request 2 -> 500 Internal Server Error

Request 3 -> 200 OK

Prüfen Sie danach:

• Respektiert der Agent Retry-After?
• Nutzt er Backoff mit Jitter?
• Ist die Zahl der Wiederholungsversuche begrenzt?
• Bricht er nach wiederholtem Fehlschlag kontrolliert ab?
• Öffnet er bei einem dauerhaft fehlerhaften Dienst einen Circuit Breaker?
• Führt ein Retry bei nicht idempotenten Aktionen zu Duplikaten?

Für schreibende oder irreversible Aktionen sollten Sie einen Idempotenzschlüssel einsetzen. Dadurch wird ein wiederholter Request nicht automatisch zu einer doppelten Abbuchung, Bestellung oder E-Mail.

Simulieren Sie Ratenbegrenzungen explizit. Lesen Sie dazu den Leitfaden, was eine „rate-limit-exceeded“-Antwort bedeutet, und bauen Sie diesen Fall als wiederholbaren Test in Ihre Pipeline ein. Weitere Muster für Retries, Timeouts, Backoff und Circuit Breaker finden Sie im Leitfaden zur Fehlerbehebung von KI-Agenten.

Fehlermodus 3: Nicht-deterministische Ausgabe

Auch mit Temperatur 0 ist die Ausgabe eines LLM nicht garantiert byte-identisch. Hardware, Batching, Modellupdates und Anbieteränderungen können Variationen erzeugen. Der vLLM-Thread zu Seeds und Reproduzierbarkeit zeigt, warum Temperatur und Seed allein dafür nicht ausreichen.

Exakte String-Vergleiche machen Ihre Tests instabil. Instabile Tests werden früher oder später ignoriert — und sind damit oft schlimmer als keine Tests.

Testen Sie Struktur und Bedeutung statt Wortlaut

Vermeiden Sie Tests wie:

expect(answer).toBe("Der Gesamtbetrag beträgt 42 Euro.");

Testen Sie stattdessen strukturierte Eigenschaften:

expect(response.totalAmount).toBeGreaterThanOrEqual(0);
expect(response.totalAmount).toBeLessThanOrEqual(cart.totalAmount);
expect(response.currency).toBe("EUR");
expect(response.items).toHaveLength(cart.items.length);

Für Tool-Aufrufe können Sie prüfen:

• korrekter Tool-Name
• erlaubter Endpunkt
• gültige Request-Struktur
• erforderliche Schlüssel
• keine verbotenen Felder
• Werte innerhalb plausibler Bereiche

Beispiel:

expect(toolCall.name).toBe("create_reservation");
expect(toolCall.arguments.guests).toBeGreaterThan(0);
expect(toolCall.arguments.date).toMatch(/^\d{4}-\d{2}-\d{2}$/);

Ein Test wie „Die Antwort enthält einen Gesamtbetrag zwischen 0 und dem Warenkorbwert“ übersteht natürliche Modellvariation und erkennt trotzdem echte Regressionen.

Mehr dazu finden Sie im Leitfaden zum Testen nicht-deterministischer KI-Agenten. Der Artikel über Funktionsweise von Agenten-Speicher zeigt außerdem, warum zustandsbehaftete Agenten zusätzliche Testfälle benötigen.

Fehlermodus 4: Ausufernde Kosten

Agenten arbeiten in Schleifen, und Schleifen kosten Tokens, Zeit und Geld. Ein festgefahrener Agent kann einen fehlgeschlagenen Aufruf tausendfach wiederholen und eine kleine Rechnung über Nacht erheblich erhöhen.

Kosten sind nicht nur ein Finanzthema. Die Fehler, die Kosten verursachen, machen Agenten meist auch langsam und unberechenbar:

• Endlosschleifen
• redundante Tool-Aufrufe
• übergroßer Kontext
• Wiederholungen ohne Obergrenze
• unnötig lange Planungs- oder Reflexionsschritte

Messen Sie Kosten im Test

Erfassen Sie pro Agentenlauf mindestens:

- Anzahl der Tool-Aufrufe
- Anzahl der Retries
- Token-Eingabe
- Token-Ausgabe
- geschätzte Kosten
- Laufzeit

Definieren Sie harte Limits:

const MAX_TOOL_CALLS = 8;
const MAX_RETRIES_PER_TOOL = 3;
const MAX_TOKEN_BUDGET = 20_000;

Ein Test sollte nicht nur erfolgreich sein, sondern auch effizient:

expect(metrics.toolCalls).toBeLessThanOrEqual(MAX_TOOL_CALLS);
expect(metrics.retries).toBeLessThanOrEqual(MAX_RETRIES_PER_TOOL);
expect(metrics.totalTokens).toBeLessThanOrEqual(MAX_TOKEN_BUDGET);

Wenn ein Agent zwar erfolgreich antwortet, dafür aber 40 Requests benötigt, haben Sie wahrscheinlich bereits einen zukünftigen Kosten- oder Stabilitätsvorfall entdeckt.

Konkrete Optimierungshebel finden Sie im Leitfaden zur Reduzierung der Token-Kosten von Agenten über die CLI.

Fehlermodus 5: Fehlende Schutzmaßnahmen

Die teuersten Fehler passieren oft dann, wenn der Agent technisch korrekt handelt, die Aktion aber nicht hätte ausführen dürfen.

Beispiele:

• E-Mail wird ohne Freigabe versendet.
• Datensatz wird gelöscht.
• Bestellung wird ausgelöst.
• Berechtigung wird geändert.
• Kundendaten werden an einen externen Dienst übertragen.

Zwischen der Entscheidung des Modells und einer echten Seiteneffekt-Aktion muss eine Schutzschicht liegen.

Implementieren Sie Guardrails für Seiteneffekte

Nutzen Sie eine Positivliste für automatisch erlaubte Aktionen:

const ALLOWED_AUTOMATIC_ACTIONS = [
  "get_customer",
  "search_knowledge_base",
  "create_draft"
];

Schützen Sie irreversible Aktionen durch eine explizite Bestätigung:

const REQUIRES_APPROVAL = [
  "send_email",
  "delete_record",
  "create_order",
  "issue_refund"
];

Ein möglicher Kontrollfluss:

if (REQUIRES_APPROVAL.includes(toolCall.name)) {
  return {
    status: "approval_required",
    proposedAction: toolCall
  };
}

return executeTool(toolCall);

Ergänzen Sie einen Trockenlaufmodus:

if (dryRun) {
  return {
    status: "dry_run",
    action: toolCall,
    message: "Aktion wurde nicht ausgeführt."
  };
}

Testen Sie die Guardrail, nicht nur den Happy Path

Simulieren Sie einen seiteneffektbehafteten Endpunkt und prüfen Sie:

1. Der Agent erkennt, dass eine Genehmigung erforderlich ist.
2. Der Live-Endpunkt wird ohne Freigabe nicht aufgerufen.
3. Der Trockenlauf erzeugt keinen Seiteneffekt.
4. Nach einer gültigen Freigabe wird genau eine Aktion ausgeführt.

Die OWASP Top 10 für LLM-Anwendungen sind eine gute Checkliste für weitere Risiken. Der Leitfaden zu KI-Agenten-Guardrails behandelt Genehmigungstore und die Begrenzung des Blast Radius ausführlich.

Wie Sie einen Agenten-Test strukturieren

Die fünf Fehlermodi folgen derselben wiederverwendbaren Testform.

1. Tool-Schemata erfassen

Definieren Sie für jedes Tool:

• Endpunkt
• HTTP-Methode
• Request-Schema
• Response-Schema
• Authentifizierungsanforderungen
• erlaubte Fehlercodes
• Seiteneffekt-Risiko

2. Abhängigkeiten simulieren

Mocken Sie externe APIs, um Folgendes kontrollieren zu können:

• Statuscodes
• Antwortzeiten
• Header wie Retry-After
• fehlerhafte Bodies
• Netzwerkfehler
• Seiteneffekte

3. Den Agenten durch Fehlerpfade führen

Testen Sie nicht nur erfolgreiche Antworten. Führen Sie gezielt Szenarien aus wie:

429 -> 500 -> 200
Timeout -> Retry -> Timeout -> Controlled failure
200 mit ungültigem JSON
200 mit fehlendem Pflichtfeld
Destruktiver Tool-Aufruf ohne Genehmigung

4. Requests und Verhalten prüfen

Validieren Sie:

• Form der ausgehenden Anfrage
• Anzahl der Tool-Aufrufe
• Retry-Verhalten
• Backoff-Verhalten
• Einhaltung des Token-Budgets
• ausgelöste Guardrails
• Struktur der finalen Antwort

Beginnen Sie mit einem Tool und erweitern Sie den Test schrittweise. Die Einrichtung zahlt sich aus, sobald ein fehlerhafter Tool-Aufruf im CI erkannt wird statt erst durch einen Benutzer.

Checkliste: Agenten vor dem Produktionsstart

• [ ] Jeder Tool-Aufruf wird gegen ein Schema validiert.
• [ ] Vertragsverletzungen lassen Tests fehlschlagen.
• [ ] 429, 500 und Timeouts werden simuliert.
• [ ] Der Agent nutzt begrenzte Retries und Backoff.
• [ ] Wiederholte Schreibaktionen sind idempotent.
• [ ] Tests prüfen Struktur und Bedeutung statt exakter Texte.
• [ ] Token-Nutzung und Tool-Aufrufe pro Lauf werden gemessen.
• [ ] Budgetgrenzen stoppen ausufernde Schleifen.
• [ ] Destruktive Aktionen sind per Allowlist oder Genehmigung geschützt.
• [ ] Der Guardrail-Pfad wird mit Mocks getestet.
• [ ] Trockenläufe lösen keine echten Seiteneffekte aus.

Wenn diese Punkte abgedeckt sind, haben Sie die häufigsten produktionsrelevanten Agentenfehler getestet.

Wo Apidog passt — und wo nicht

Apidog ist kein Agenten-Framework, kein Modell-Host und keine Evaluierungsumgebung. Es baut oder betreibt Ihren Agenten nicht.

Seine Rolle liegt in der API-Schicht, von der Ihr Agent abhängt:

1. API-Verträge definieren und speichern
   
   Beschreiben Sie die Tools, Endpunkte sowie Request- und Response-Schemas.

2. Abhängigkeiten simulieren
   
   Erzeugen Sie kontrolliert Antworten wie 429, 500, Timeouts oder fehlerhafte Response-Bodies.

3. Antworten und Requests validieren
   
   Prüfen Sie Schema, Datentypen, Pflichtfelder, Wertebereiche und andere Assertions.

Das ist die praktische Einordnung: Apidog testet die APIs, die Ihr Agent aufruft, simuliert die Fehler, die Ihr Code behandeln muss, und prüft, was zurückkommt. Der Überblick über agentisches KI-Testen ordnet diesen Ansatz in eine umfassendere QA-Strategie ein.

Häufig gestellte Fragen

Ist Agentenzuverlässigkeit ein Modell- oder ein Engineering-Problem?

Meistens ein Engineering-Problem. Die Modellwahl ist wichtig, aber viele produktionsrelevante Fehler entstehen durch ungültige Tool-Aufrufe, unbehandelte Ratenbegrenzungen, fehlende Idempotenz und unzureichende Schutzmaßnahmen.

Kann ich Agenten testen, ohne echte APIs aufzurufen?

Ja — und das sollten Sie. Simulieren Sie Abhängigkeiten, um Fehlerantworten zu erzwingen, Timing zu kontrollieren und echte Seiteneffekte zu vermeiden. Nur so lassen sich Wiederherstellungs- und Guardrail-Pfade zuverlässig testen.

Wie teste ich, wenn die Ausgabe bei jedem Lauf variiert?

Prüfen Sie Struktur und Bedeutung statt exakter Texte. Validieren Sie JSON-Schemas, Tool-Aufruf-Formen, Pflichtfelder und Wertebereiche. Der Leitfaden zum Testen nicht-deterministischer KI-Agenten erklärt die Strategien ausführlich.

Was sollte ich zuerst testen?

Beginnen Sie mit Schutzmaßnahmen für destruktive Aktionen und mit der Fehlerbehandlung für externe APIs. Diese beiden Bereiche verhindern die teuersten Vorfälle: schädliche Seiteneffekte und budgetverbrauchende Schleifen.

Beginnen Sie mit einem Fehlermodus

Sie müssen nicht alle fünf Fehlermodi sofort abdecken. Wählen Sie den riskantesten für Ihren Agenten — oft Guardrails oder Fehlerbehandlung — und simulieren Sie ihn diese Woche.

Programmieren Sie den Fehler. Führen Sie den Agenten aus. Prüfen Sie Requests, Retries, Kosten und Seiteneffekte.

Wenn Ihr Agent einen simulierten 429 mit sauberem Backoff behandelt, statt in eine budgetzehrende Schleife zu geraten, ist das ein belastbarer Grund für Vertrauen — deutlich besser als eine grüne Demo.

Laden Sie Apidog herunter, um API-Verträge zu entwerfen, Fehler zu simulieren und die Antworten zu validieren, von denen Ihr Agent abhängt.