Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Überwachung und Protokollierung

Lektion 13 von 14 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Beobachtung Ihres Agents in der Produktion
  2. Die drei Ebenen der Protokollierung
  3. Zu überwachende Metriken
  4. Überwachungs-Dashboard
  5. Automatische Warnungen
  6. Kernaussagen

Lektion aktualisiert am 3. November 2026 basierend auf OpenAIs Computer use-Guide und der Dokumentation der Responses API: Die Protokollierung liest nun Aktionen aus einem computer_call und Elemente aus response.output (Nachrichten mit ihrem phase, Zusammenfassungen des Denkprozesses, Aufrufe), anstatt der tool_use-Blöcke aus der Anthropic API. Die fest codierten Preise für Claude Sonnet wurden durch die Preise des verwendeten Modells ersetzt, und die veraltete Funktion datetime.utcnow() (seit Python 3.12) wurde durch datetime.now(timezone.utc) ersetzt. Quellen: Computer use · Pricing.

Beobachtung Ihres Agents in der Produktion

Ein Computer-Use-Agent in der Produktion ist eine Black Box, wenn Sie keine geeignete Überwachung einrichten. Im Gegensatz zu einer Standard-API, bei der Sie nur Anfragen und Antworten protokollieren, müssen Sie hier auch visuelle Aktionen, Screenshots und die Entscheidungen des Modells verfolgen. Der Unterschied ist konkret: Wenn ein Workflow um 3 Uhr morgens fehlschlägt, ist die entscheidende Frage nicht „welche Ausnahme wurde geworfen”, sondern „was hat der Agent gesehen und warum hat er dort geklickt?”. Ein Protokoll, das diese Frage nicht beantwortet, hilft Ihnen am nächsten Morgen nicht weiter.

Die drei Ebenen der Protokollierung

Instrumentierung basiert daher auf drei sich ergänzenden Ebenen: Was der Agent getan hat, was er dachte, bevor er es tat, und was er sah, als er entschied. Jede Ebene schreibt in einen anderen Kanal, da weder das Volumen noch die nützliche Lebensdauer gleich sind.

Ebene 1: Aktionen

Jede vom Agenten ausgeführte Aktion muss protokolliert werden. Das untenstehende Format prefixiert systematisch die Iterationsnummer und den Namen des aktuellen Schritts, sodass Sie ein Protokoll mit mehreren tausend Zeilen auf die einzelne fehlerhafte Sequenz filtern können. Aktionen kommen als Objekte aus dem computer_call an, mit denselben Feldern wie in Ihrem Handler (x, y, scroll_x, keys…). Beachten Sie die Handhabung der Aktion vom Typ type: Wir erfassen die Länge des eingegebenen Textes, niemals dessen Inhalt. Ein Agent, der ein Login-Formular ausfüllt, gibt ein Passwort ein, und die Regel aus der vorherigen Lektion gilt hier ohne Ausnahme.

import logging

logger = logging.getLogger("computer_use")
logger.setLevel(logging.INFO)

handler = logging.FileHandler("agent.log")
handler.setFormatter(logging.Formatter("%(asctime)s | %(levelname)s | %(message)s"))
handler.addFilter(SensitiveFilter())  # Filter aus Lektion 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Protokolliert eine Aktion aus einem computer_call."""
    prefix = f"[iter={iteration}] [{step}]"
    match action.type:
        case "click" | "double_click" | "move":
            logger.info("%s %s at (%s, %s)", prefix, action.type.upper(), action.x, action.y)
        case "type":
            # Niemals den Text selbst: nur seine Länge
            logger.info("%s TYPE (%d chars)", prefix, len(action.text))
        case "scroll":
            logger.info("%s SCROLL dx=%s dy=%s", prefix, action.scroll_x, action.scroll_y)
        case "keypress":
            logger.info("%s KEYPRESS %s", prefix, "+".join(action.keys))
        case "drag":
            logger.info("%s DRAG (%d points)", prefix, len(action.path))
        case _:
            logger.info("%s %s", prefix, action.type.upper())

Ebene 2: Modellentscheidungen

Protokollieren Sie, was das Modell über seine Entscheidungen sagt, um zu verstehen, warum es eine bestimmte Aktion gewählt hat. Ein Klick an unerwarteten Koordinaten bedeutet an sich nichts; gepaart mit dem Satz, der ihm vorausging – „die Absendeschaltfläche scheint durch das Cookie-Banner verdeckt” – wird daraus eine Diagnose. Der Text wird auf zweihundert Zeichen gekürzt, was mehr als genug ist, um die Absicht zu erfassen, ohne das Dateivolumen zu sprengen. Zwei Quellen für Text existieren in einer Responses-API-Antwort. Zwischenmessages, die das Modell vor dem Handeln schreibt, tragen phase: "commentary", während die finale Antwort phase: "final_answer" trägt. Und wenn das verwendete Modell Zusammenfassungen des Denkprozesses unterstützt, erhalten Sie diese, indem Sie sie anfordern (reasoning={"summary": "auto"}): Sie kommen in Elementen vom Typ reasoning an.

Der Tokenverbrauch wird im gleichen Rhythmus protokolliert und verdient besondere Aufmerksamkeit: Selbst mit previous_response_id werden alle Eingabetokens aus vorherigen Antworten in der Kette erneut als Eingabe abgerechnet, einschließlich Screenshots. Die Kosten einer Runde steigen daher mit der Länge der Sitzung.

def log_model_response(response, iteration: int):
    """Protokolliert Notizen, Zusammenfassungen und Aufrufe aus einer Antwort (ohne Bilder)."""
    for item in response.output:
        if item.type == "reasoning":
            for summary in item.summary:
                logger.info("[iter=%d] REASONING: %s", iteration, summary.text[:200])
        elif item.type == "message":
            text = "".join(c.text for c in item.content if c.type == "output_text")
            logger.info("[iter=%d] MESSAGE (%s): %s", iteration, item.phase or "-", text[:200])
        elif item.type == "computer_call":
            actions = ", ".join(a.type for a in item.actions or [])
            logger.info("[iter=%d] COMPUTER_CALL %s: %s", iteration, item.call_id, actions)
        elif item.type == "function_call":
            logger.info("[iter=%d] FUNCTION_CALL %s", iteration, item.name)

    # Verwendete Tokens
    logger.info(
        "[iter=%d] TOKENS: in=%d out=%d",
        iteration, response.usage.input_tokens, response.usage.output_tokens,
    )

Ebene 3: Screenshots

Speichern Sie Screenshots zur Post-Mortem-Fehlersuche, aber achten Sie auf Ihren Festplattenspeicher: Eine PNG-Aufnahme wiegt oft mehrere hundert Kilobyte, und ein langer Workflow produziert hunderte davon. Die Klasse unten löst dies durch einfache Rotation. Der Dateiname beginnt mit einem Zeitstempel, wodurch die alphabetische Reihenfolge der chronologischen entspricht; das Sortieren in _cleanup reicht dann aus, um die ältesten Aufnahmen zu identifizieren und zu löschen, bis man wieder unter der Obergrenze von hundert Dateien ist. Das Feld label ermöglicht es Ihnen, interessante Momente zu annotieren, beispielsweise error oder before_validation, und sie im Ordner auf einen Blick zu finden.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Speichert Screenshots mit Rotation."""

    def __init__(self, base_dir: str = "logs/screenshots", max_files: int = 100):
        self.base_dir = Path(base_dir)
        self.base_dir.mkdir(parents=True, exist_ok=True)
        self.max_files = max_files
        self.counter = 0

    def save(self, screenshot_bytes: bytes, iteration: int, label: str = ""):
        """Speichert einen Screenshot mit einem beschreibenden Namen."""
        ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
        filename = f"{ts}_iter{iteration:03d}_{label}.png"
        filepath = self.base_dir / filename

        with open(filepath, "wb") as f:
            f.write(screenshot_bytes)

        self.counter += 1
        self._cleanup()

        return filepath

    def _cleanup(self):
        """Löscht alte Screenshots."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Zu überwachende Metriken

Erfolgsquote
pro Workflow
Durchschnittliche
Dauer pro Schritt
Kosten
in Tokens pro Ausführung
Fehler
nach Typ und Häufigkeit

Diese vier Indikatoren sind nur dann wertvoll, wenn sie im Zeitverlauf miteinander verglichen werden: Ein Rückgang der Erfolgsquote eines Workflows von 95 auf 80 Prozent zeigt Ihnen, dass sich eine Benutzeroberfläche verschoben hat, lange bevor sich der erste Benutzer beschwert. Implementieren Sie daher einen Metrik-Sammler, der jeder Ausführung angehängt ist. Die WorkflowMetrics-Datenklasse sammelt Tokens Iteration für Iteration, verfolgt Fehler mit ihrem Schritt und Zeitstempel und stellt zwei berechnete Eigenschaften bereit: Dauer, die funktioniert, auch wenn der Workflow noch nicht abgeschlossen ist, und eine Kostenschätzung basierend auf den Preisen des verwendeten Modells, die Sie von der OpenAI Preisseite übernehmen, anstatt sie fest zu codieren. Die summary-Methode erzeugt das kompakte Wörterbuch, das Sie bei jeder Ausführung archivieren.

from dataclasses import dataclass, field
from datetime import datetime, timezone

def now() -> datetime:
    return datetime.now(timezone.utc)

@dataclass
class WorkflowMetrics:
    """Sammelt Metriken für einen Workflow."""
    workflow_id: str
    input_price_per_million: float  # Preis für das verwendete Modell
    output_price_per_million: float
    start_time: datetime = field(default_factory=now)
    end_time: datetime | None = None
    iterations: int = 0
    total_input_tokens: int = 0
    total_output_tokens: int = 0
    errors: list = field(default_factory=list)
    steps_completed: int = 0
    steps_total: int = 0

    def record_iteration(self, response):
        self.iterations += 1
        self.total_input_tokens += response.usage.input_tokens
        self.total_output_tokens += response.usage.output_tokens

    def record_error(self, error: str, step: str):
        self.errors.append({
            "step": step,
            "error": error,
            "timestamp": now().isoformat(),
        })

    def finalize(self):
        self.end_time = now()

    @property
    def duration_seconds(self) -> float:
        end = self.end_time or now()
        return (end - self.start_time).total_seconds()

    @property
    def estimated_cost_usd(self) -> float:
        # Schätzung: Prompt-Caching und eine gehostete Umgebung werden nicht gezählt
        input_cost = self.total_input_tokens / 1_000_000 * self.input_price_per_million
        output_cost = self.total_output_tokens / 1_000_000 * self.output_price_per_million
        return input_cost + output_cost

    def summary(self) -> dict:
        return {
            "workflow_id": self.workflow_id,
            "duration_s": round(self.duration_seconds, 1),
            "iterations": self.iterations,
            "tokens": self.total_input_tokens + self.total_output_tokens,
            "cost_usd": round(self.estimated_cost_usd, 4),
            "success": len(self.errors) == 0,
            "errors": len(self.errors),
            "steps": f"{self.steps_completed}/{self.steps_total}",
        }

Überwachungs-Dashboard

Für die Echtzeitüberwachung senden Sie Metriken an einen Überwachungsdienst, anstatt sie in einer Datei schlafen zu lassen. Die Funktion unten sendet die zeitgestempelte Zusammenfassung an einen HTTP-Endpunkt, wobei zwei Vorsichtsmaßnahmen so wichtig sind wie der Versand selbst: eine maximale Verzögerung von fünf Sekunden und eine abgefangene Ausnahme, die sich mit einer Warnung begnügt. Ein nicht verfügbarer Metrik-Sammler darf den Workflow, den er beobachtet, niemals herunterfahren – das Gegenteil wäre die Definition von kontraproduktiver Aufsicht.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Sendet Metriken an einen Überwachungsdienst."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # requests setzt den JSON-Header selbst
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Metrik-Versandfehler: {e}")

Automatische Warnungen

Ein Dashboard, das niemand beobachtet, ist nur ein Archiv. Richten Sie daher Warnungen basierend auf Schwellenwerten ein, sodass die Anomalie zu Ihnen kommt. Die vier hier beibehaltenen Bedingungen decken klassische Drifts ab: Kosten höher als zwei Dollar, eine Dauer, die drei Minuten überschreitet, mehr als 30 Iterationen oder mehr als zwei Fehler in derselben Ausführung. Diese Werte sind Ausgangspunkte, keine Wahrheiten: Kalibrieren Sie sie anhand von Messungen aus Ihren eigenen erfolgreichen Ausführungen und platzieren Sie die Schwelle deutlich über Ihrem beobachteten Median. Eine Warnung, die jeden Tag auslöst, wird ab der zweiten Woche ignoriert.

def check_alerts(metrics: WorkflowMetrics):
    """Überprüft Schwellenwerte und löst Warnungen aus."""
    alerts = []

    if metrics.estimated_cost_usd > 2.0:
        alerts.append(f"Hohe Kosten: ${metrics.estimated_cost_usd:.2f}")

    if metrics.duration_seconds > 180:
        alerts.append(f"Übermäßige Dauer: {metrics.duration_seconds:.0f}s")

    if metrics.iterations > 30:
        alerts.append(f"Zu viele Iterationen: {metrics.iterations}")

    if len(metrics.errors) > 2:
        alerts.append(f"Mehrfache Fehler: {len(metrics.errors)}")

    for alert in alerts:
        logger.warning(f"WARNUNG: {alert}")
        # Senden von Benachrichtigung (E-Mail, Slack, etc.)

    return alerts

Machen Sie es zur Gewohnheit, check_alerts direkt nach finalize und dann push_metrics aufzurufen: Sie erhalten eine archivierte Spur bei jeder Ausführung, ein Signal, das an das Dashboard gesendet wird, und eine Benachrichtigung nur, wenn etwas Ihre Aufmerksamkeit verdient.

Kernaussagen

  • Protokollieren Sie Aktionen, Modellnachrichten und Zusammenfassungen sowie Aufnahmen auf drei getrennten Ebenen
  • Überwachen Sie Erfolgsquote, Dauer, Tokenkosten und Fehler; die verkettete Historie wird bei jeder Runde erneut als Eingabe abgerechnet
  • Implementieren Sie Screenshots-Rotation, um die Festplatte nicht zu überlasten
  • Richten Sie automatische Warnungen an kritischen Schwellenwerten ein
  • Protokollieren Sie niemals sensible Daten (Passwörter, Tokens, personenbezogene Daten)