Observability für KI-Agenten: Monitoring von Agentensystemen

Idee in 30 Sekunden

Observability für KI-Agenten zeigt, was während eines einzelnen Runs passiert.

Ein Agent kann Dutzende Schritte ausführen: Reasoning, Tool-Aufrufe, wiederholte LLM-Aufrufe.

Observability macht diese Schritte über Tracing, Logs und Metriken sichtbar.

Hauptproblem

In einem klassischen Backend führt ein HTTP-Request vorhersehbaren Code aus:

request → handler → database → response

Die Anzahl der Schritte ist vorab bekannt, und das Verhalten lässt sich mit normalen Logs leicht verfolgen.

In Systemen mit KI-Agenten läuft es anders: Eine Anfrage kann zu einem Run mit mehreren Reasoning-Schritten, Tool-Aufrufen und wiederholten Iterationen werden.

Ein Agent kann 2 Schritte oder 20 machen. Er kann mehrere Tools aufrufen, Reasoning mehrfach wiederholen und mehr Tokens verbrauchen als erwartet.

Ohne Observability ist es schwer, selbst grundlegende Fragen zu beantworten:

• Warum ist die Anfrage langsam?
• Warum sind die Token-Kosten plötzlich gestiegen?
• Warum ruft der Agent ein Tool dutzende Male auf?
• In welchem Schritt ist der Fehler entstanden?

Für solche Systeme reichen normale Logs nicht aus. Observability ist nötig, um den vollständigen Ausführungspfad zu sehen und problematische Schritte beim Debugging schnell zu finden.

Wie es funktioniert

Observability für KI-Agenten basiert auf drei Signaltypen: Traces, Logs und Metriken. Zusammen zeigen sie sowohl einzelne Anfragen als auch den Gesamtzustand des Systems.

Es gibt spezialisierte Observability-Tools für Agenten (zum Beispiel LangSmith, Langfuse, Arize Phoenix), aber die Grundprinzipien sind unabhängig vom Tool gleich.

Tracing

Tracing zeigt den vollständigen Ausführungspfad eines Agent-Runs. Jeder Schritt wird als Ereignis erfasst: Modell-Reasoning, Tool-Aufruf oder Ergebnis. Ein Trace besteht aus Spans (spans). Ein Trace ist der gesamte Ausführungspfad (run), ein Span ist ein einzelner Schritt darin, z. B. ein Tool-Aufruf oder Reasoning.

run_id: 9fd2

step 1 — search_docs       420ms
step 2 — summarize         110ms
step 3 — generate_answer   890ms

Tracing zeigt, welche Tools der Agent aufgerufen hat und wie viele Schritte er gemacht hat. Außerdem sieht man, wo ein Fehler oder eine Verzögerung auftrat.

Wie ein Agent-Trace aussieht

Tracing lässt sich am einfachsten über eine reale Anfrage verstehen.

Beispiel-Trace einer einzelnen Anfrage:

run_id: 9fd2
user_query: "Find recent research about battery recycling"

step 1  llm_reasoning        320ms
        thought: need to search research papers

step 2  tool_call: search    410ms
        query: battery recycling research 2024

step 3  llm_reasoning        180ms
        thought: summarize the most relevant papers

step 4  tool_call: fetch     260ms
        source: arxiv

step 5  llm_generate         720ms
        output: final answer

Dieser Trace zeigt schnell:

• welche Schritte der Agent ausgeführt hat
• welche Tools aufgerufen wurden
• wie lange jeder Schritt gedauert hat
• wo Verzögerung oder Fehler entstanden

In Production-Systemen enthält ein Trace oft zusätzliche Informationen:

• run_id und trace_id zur Ereigniskorrelation
• Latenz jedes Schritts
• LLM token usage
• stop reason (completed, max_steps, tool_error)

Traces sind nicht nur für Debugging nützlich. Sie sind auch für Evaluations wichtig. Ohne Zwischen-Schritte ist es schwer, automatisch zu prüfen, ob der Agent im Run korrekt gehandelt hat und nicht nur eine gute finale Antwort geliefert hat.

Logging

Logs erfassen Ereignisse während der Agent-Ausführung:

• Start und Ende des Runs
• Tool-Aufrufe mit Parametern
• Fehler und Exceptions
• stop reason des Agenten

Logs beantworten die Frage „was ist passiert“. Tracing beantwortet „wie genau ist es passiert“.

Metriken

Metriken zeigen den Gesamtzustand des Systems, nicht nur eine einzelne Anfrage. Typische Production-Metriken für Agenten:

Metriken sind für Monitoring und Alerts in Production nötig. Sie machen Anomalien schnell sichtbar: zum Beispiel plötzlichen Anstieg von token usage, latency oder Anzahl von tool calls.

Die meisten LLM-Provider (OpenAI, Anthropic) liefern token usage direkt in der Antwort. Meist muss man das daher nicht manuell berechnen, sondern nur diese Felder loggen.

Wann einsetzen

Observability ist nicht immer notwendig.

Für einfache Szenarien reicht meist Basis-Logging. Zum Beispiel bei einem einzelnen LLM-Aufruf ohne Tools und ohne Ausführungsschleife.

Sobald aber ein Run mehrere Schritte hat — Reasoning, Tool-Aufrufe, wiederholte Iterationen — wird es ohne Observability schwer, das System zu debuggen, Kosten zu steuern und Verhalten zu erklären.

Implementierungsbeispiel

Unten ist ein vereinfachtes Beispiel für Instrumentation im Agent-Runtime. In realen Systemen werden diese Ereignisse meist an ein Tracing-System oder eine Observability-Plattform gesendet. In den meisten Runtime-Systemen ist jeder Ausführungsschritt als step modelliert: das kann Modell-Reasoning oder ein Tool-Aufruf sein. Diese Schleife (agent.iter) wird in Frameworks wie LangGraph, CrewAI und in eigenen Runtime-Implementierungen genutzt.

import logging
import time
import uuid

logger = logging.getLogger("agent")

def run_agent(agent, task):
    run_id = str(uuid.uuid4())

    logger.info("agent_run_started", extra={
        "run_id": run_id,
        "task": task,
    })

    steps = []

    for step in agent.iter(task):  # step: reasoning oder tool execution
        step_start = time.time()
        result = step.execute()
        latency = time.time() - step_start

        step_event = {
            "run_id": run_id,
            "step_type": step.type,  # reasoning | tool_call | llm_generate
            "tool": getattr(step, "tool_name", None),
            "latency": latency,
        }

        logger.info("agent_step", extra=step_event)
        steps.append(step_event)

        if result.is_final:
            break

    logger.info("agent_run_finished", extra={
        "run_id": run_id,
        "steps": len(steps),
    })

Tools kann man in einen Wrapper legen und sowohl erfolgreiche Aufrufe als auch Fehler loggen:

def traced_tool(tool_fn):
    def wrapper(*args, **kwargs):
        start = time.time()

        try:
            result = tool_fn(*args, **kwargs)
            logger.info(
                "tool_call",
                extra={
                    "tool": tool_fn.__name__,
                    "latency": time.time() - start,
                    "status": "ok",
                },
            )
            return result
        except Exception as error:
            logger.error(
                "tool_call_failed",
                extra={
                    "tool": tool_fn.__name__,
                    "latency": time.time() - start,
                    "error": str(error),
                },
            )
            raise

    return wrapper

Das obige Beispiel zeigt Basis-Instrumentation. In Production-Systemen wird sie meist durch mehrere Praktiken ergänzt:

• trace_id für jeden Run
• strukturierte Logs (JSON)
• Metriken für latency und token usage
• Integration mit Monitoring-Systemen

Zum Beispiel kann ein strukturierter Log-Eintrag so aussehen:

{
  "timestamp": "2026-03-21T15:17:00Z",
  "level": "INFO",
  "event": "tool_call",
  "run_id": "9fd2...",
  "tool": "search_docs",
  "latency_ms": 410,
  "status": "ok"
}

In realen Systemen sollten run_id und trace_id durch die ganze Aufrufkette propagiert werden. In Python wird dafür oft contextvars genutzt, damit der Identifier nicht in jede Funktion als Argument durchgereicht werden muss.

So sieht man den vollständigen Ausführungspfad des Agenten und findet problematische Schritte schneller.

Typische Fehler

Selbst wenn Observability bereits eingebaut ist, bleiben Agentensysteme oft schwer zu diagnostizieren. Meist wegen der typischen Fehler unten.

Nur die finale Antwort loggen

Wenn das System nur das finale Ergebnis loggt, ist nicht nachvollziehbar, wie der Agent dorthin gekommen ist. Deshalb ist es wichtig, Reasoning-Schritte, Tool-Aufrufe und stop reason zu loggen. Ohne das sind selbst einfache Post-Release-Incidents schwer zu analysieren.

Keine Traces für Tool-Aufrufe

Tools sind oft der langsamste Teil des Systems. Wenn Tool-Aufrufe nicht im Trace sind, ist schwer zu verstehen:

• welches Tool Verzögerung verursacht
• wo genau der Fehler entsteht
• ob der Agent dasselbe Tool wiederholt aufruft

In Production maskiert das oft Tool-Spam oder eine frühe Phase von kaskadierenden Ausfällen.

Keine Kosten-Metriken

Agenten können Kosten unbemerkt erhöhen: durch lange Reasoning-Schleifen, wiederholte LLM-Aufrufe oder unnötige tool calls. Ohne Kosten-Metriken merkt man das oft erst bei deutlich höheren Rechnungen. Dadurch kann das System schnell in einen teuren und instabilen Betriebsmodus wechseln.

Rohes Logging von Prompts

Prompts können personenbezogene Daten, Secrets oder interne Informationen enthalten. Vor dem Logging sollten sie redigiert oder anonymisiert werden. Sonst können sensible Daten bei Incidents in Logs landen.

Selbstcheck

Unten ist eine kurze Checkliste für grundlegende Production-Observability.

FAQ

Q: Was ist der Unterschied zwischen Tracing, Logs und Metriken?
A: Tracing zeigt den Pfad eines einzelnen Runs Schritt für Schritt. Logs erfassen Ereignisse und Fehler. Metriken zeigen das Gesamtbild über einen Zeitraum (latency, error rate, token usage).

Q: Was zuerst einführen, wenn noch keine Observability existiert?
A: Startet mit dem Minimum: run_id, strukturierte Logs und latency pro Schritt. Danach Tracing für Tool-Aufrufe und Kern-Metriken (token usage, tool calls per run, error rate).

Q: Welche Felder sind für Debugging eines problematischen Runs am wichtigsten?
A: Minimum: run_id/trace_id, Schritt-Typ, aufgerufenes Tool, Schritt-Latenz, stop reason, Fehler (falls vorhanden). Das reicht, um die Ereigniskette zu rekonstruieren.

Q: Muss man direkt externe Observability-Tools einsetzen?
A: Nein. Ihr könnt mit eigener Instrumentation und strukturierten Logs starten. Spezialisierte Plattformen lohnen sich, wenn Run-Volumen, Teamzahl und Bedarf an zentralisierter Analyse wachsen.

Verwandte Seiten

Nächste Seiten zum Thema:

• Agent Tracing — wie man die Ausführung eines einzelnen Runs verfolgt.
• Verteiltes Agent-Tracing — Tracing zwischen mehreren Agenten.
• Agent-Metriken — welche Kennzahlen gemessen werden sollten.