Wenn Sie es nicht wiederholen können, haben Sie es nicht verstanden
Ein Agenten-Lauf ist nicht-deterministisch. Genau deshalb braucht er mehr Instrumentierung als klassische Software, nicht weniger: ein Span je Tool-Call, deterministisches Replay für die Fehlersuche, eine Eval-Suite in der CI und Kosten, die einem Use Case zugeordnet sind.
Agenten-Observability macht einen Lauf nachträglich erklärbar. Jeder Tool-Call erzeugt einen OpenTelemetry-Span mit Agenten-Identität, Werkzeugname, sanitisierten Parametern, Latenz und Token-Verbrauch. Ein deterministisches Replay spielt denselben Lauf gegen aufgezeichnete Antworten erneut ab — und die Kosten liegen je Lauf, Use Case und Mandant vor.
Was in einem Span steht
Ein Trace ohne Agenten-Kontext ist nutzlos. Deshalb trägt jeder Span die Attribute, die man bei einer Fehlersuche oder einem Audit tatsächlich braucht.
| Attribut | Beispiel | Wozu |
|---|---|---|
| agent.id / agent.version | action-agent@3 | Zuordnung zu Identität und Codestand |
| run.id / step | r-8f21c9 · 4 | Verknüpfung mit dem Event Log der Runtime |
| tool.name | stripe.refund | Welches Werkzeug, welcher MCP-Server |
| tool.params_sanitized | {amount:189.00, order:sha256…} | Nachvollziehbarkeit ohne Klartext-Personendaten |
| policy.decision | allow (limit 250) | Warum der Aufruf durchging — oder nicht |
| latency.ms | 310 | Wo die Zeit hingeht |
| tokens.in / tokens.out | 4 210 / 380 | Grundlage der Kostenzuordnung |
| model.name / model.route | klein → gross | Nachweis, wann eskaliert wurde |
| cache.hit | true | Wirkung des Prompt-Caching |
| error.type | upstream_timeout | Fehlerklassifikation für Alerting |
Deterministisches Replay
Das eigentliche Problem beim Debuggen von Agenten: Der Fehler tritt beim zweiten Versuch nicht mehr auf. Replay löst das, indem der Lauf gegen die aufgezeichneten Modell- und Tool-Antworten erneut abgespielt wird — ohne echte Aufrufe, ohne neue Kosten, mit identischem Ergebnis.
Damit lassen sich drei Fragen beantworten, die sonst offen bleiben: Welche Eingabe hat die falsche Entscheidung ausgelöst? Ändert ein neuer Prompt das Verhalten in genau diesem Fall? Und hätte die neue Policy den Aufruf verhindert?
# Lauf exakt so wiederholen, wie er passiert ist — ohne echte Tool-Calls.
agentctl replay r-8f21c9
# Derselbe Lauf gegen einen geaenderten Prompt. Zeigt die Abweichung
# Schritt fuer Schritt an, statt nur das Endergebnis zu vergleichen.
agentctl replay r-8f21c9 --prompt-version 12 --diff
# Haette die neue Policy den Refund verhindert?
agentctl replay r-8f21c9 --policy ./tools.policy.yaml --dry-runfrom hostspezial.agents.eval import Suite, case, assert_tool_called
suite = Suite("refund-agent")
# Faelle kommen aus echten Laeufen: jeder produktive Fehler wird
# zum Testfall. Die Suite laeuft in der CI, nicht im Notebook.
@case(fixture="runs/r-8f21c9")
def test_refund_unter_limit(run):
assert_tool_called(run, "stripe.refund", amount=189.00)
assert run.status == "completed"
assert run.cost_eur < 0.05
@case(fixture="runs/r-3ac110")
def test_ueber_limit_geht_an_menschen(run):
# Der teuerste Fehler waere eine stille Selbstfreigabe.
assert run.status == "awaiting_approval"
assert not run.tool_called("stripe.refund")Evals gehören in die CI
„Es lief einmal im Notebook“ ist kein Deployment-Kriterium mehr. Jede Änderung an Prompt, Modell, Policy oder Werkzeugliste läuft gegen eine Suite aus echten Fällen — und zwar bevor sie in Produktion geht.
Die Suite wächst von selbst: Jeder produktive Fehlschlag wird als Fixture aufgezeichnet und zum Testfall. Nach einem halben Jahr Betrieb ist das der wertvollste Teil des Projekts — wertvoller als der Prompt.
Erfolgsquote je Fallklasse, Anteil der Eskalationen an Menschen, Kosten je erfolgreichem Task, p95-Laufzeit und die Rate falsch positiver Aktionen. Nicht: „Zufriedenheit mit der Antwort“ — das ist kein Testkriterium, sondern eine Umfrage.
Kosten, die einem Verursacher zugeordnet sind
Inferenz hat Training als dominante Workload abgelöst. Damit wird Kostensteuerung zur Architekturfrage — nicht zur Aufgabe der Buchhaltung am Monatsende.
| Ebene | Kennzahl | Beispiel | Steuerhebel |
|---|---|---|---|
| Einzelner Lauf | Kosten je Lauf | 0,031 € | Budget-Cap, Kontext-Kompaktierung |
| Use Case | Kosten je erfolgreichem Task | 0,047 € | Model-Routing, Cache-Quote |
| Team | Ausgaben je Monat | PLACEHOLDER | Quoten je Agent, Alarm bei Abweichung |
| Mandant | Weiterverrechnung | PLACEHOLDER | Attribution über Span-Labels |
Die entscheidende Kennzahl ist die zweite Zeile: Kosten je erfolgreichem Task. Sie enthält die Fehlversuche, die Retries und die Eskalationen — und ist damit die einzige Zahl, die sich mit den Kosten des bisherigen manuellen Prozesses vergleichen lässt.
Was das nicht löst
Replay reproduziert Entscheidungen gegen aufgezeichnete Antworten — es beweist nicht, dass das Modell heute dieselbe Antwort gäbe. Und Traces zeigen, was der Agent getan hat, nicht warum das Modell es für richtig hielt. Wer Begründungen braucht, muss sie als strukturierte Ausgabe erzwingen und mitprotokollieren — nachträglich rekonstruieren lässt sie sich nicht.
Observability im Detail
Können wir die Traces in unser eigenes System exportieren?
Ja. Der Export erfolgt über OTLP an ein Ziel Ihrer Wahl — Tempo, Jaeger, Datadog oder ein bestehendes SIEM. Wir betreiben den Standard-Stack auf Basis von Prometheus und Grafana, sind aber nicht darauf angewiesen.
Wie lange werden Traces aufbewahrt?
Audit-relevante Ereignisse standardmäßig 365 Tage, vollständige Trace-Details kürzer — abhängig von Volumen und vereinbarter Klasse. Die Aufbewahrung ist Teil des Auftragsverarbeitungsvertrags, nicht eine Einstellung im Produkt.
Landen personenbezogene Daten in den Traces?
Nur soweit konfiguriert. Der Collector sanitisiert Parameter vor der Ablage: Feldnamen und Typen bleiben, Klartextwerte werden gehasht oder verworfen. Welche Felder wie behandelt werden, wird je Werkzeug festgelegt und dokumentiert.
Was kostet Observability zusätzlich?
Nichts extra — sie ist Teil der Betriebspauschale. Bei sehr hohen Trace-Volumina vereinbaren wir Sampling-Regeln, damit die Ablage nicht teurer wird als der Betrieb. Details auf der Preisseite.
Wie viele Eval-Fälle braucht eine sinnvolle Suite?
Zum Start reichen 20 bis 30 Fälle, wenn sie die realen Randfälle abdecken statt den Normalfall zu wiederholen. Entscheidend ist nicht die Anzahl, sondern dass jeder produktive Fehlschlag als Fall hinzukommt.
Ersetzt Replay einen Testlauf gegen echte Systeme?
Nein. Replay prüft Entscheidungslogik gegen aufgezeichnete Antworten. Integrationsfehler — geänderte Schemata, neue Fehlercodes, verändertes Verhalten eines Werkzeugs — findet nur ein echter Lauf gegen ein Testsystem.
Weiter in der Plattform
Lassen Sie uns einen Ihrer Läufe zerlegen
Schicken Sie uns einen Prozess, der heute schon mit KI läuft. Wir instrumentieren ihn in der Sandbox und zeigen Ihnen den Span-Baum, die Kosten je Lauf und die drei Stellen, an denen er still scheitert.