Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Monitorování a logování

Lekce 13 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Pozorování tvého agenta v produkci
  2. Tři úrovně logování
  3. Metriky ke sledování
  4. Monitorovací dashboard
  5. Automatická upozornění
  6. Klíčové poznatky

Lekce aktualizována 3. listopadu 2026 na základě příručky Computer use od OpenAI a dokumentace API Responses: logování nyní čte akce z computer_call a prvky z response.output (zprávy s jejich phase, shrnutí úvah, volání), namísto bloků tool_use z API Anthropic; pevně nastavené ceny pro Claude Sonnet jsou nahrazeny cenami používaného modelu a zastaralá funkce datetime.utcnow() (od Pythonu 3.12) je nahrazena funkcí datetime.now(timezone.utc). Zdroje: Computer use · Ceník.

Pozorování tvého agenta v produkci

Agent Computer Use v produkci je černou skříní, pokud nenastavíš správné monitorování. Na rozdíl od standardního API, kde loguješ požadavky a odpovědi, zde musíš sledovat také vizuální akce, snímky obrazovky a rozhodnutí modelu. Rozdíl je konkrétní: když workflow selže ve 3 hodiny ráno, podstatná otázka nezní „jaká výjimka byla vyvolána“, ale „co agent viděl a proč tam klikl?“. Log, který na tuto otázku neodpoví, ti druhý den ráno nepomůže.

Tři úrovně logování

Instrumentace proto stojí na třech doplňkových vrstvách: co agent udělal, co si myslel předtím, než to udělal, a co viděl při rozhodování. Každá vrstva zapisuje do jiného kanálu, protože ani objem dat, ani jejich užitečná životnost nejsou stejné.

Úroveň 1: Akce

Každá akce provedená agentem musí být sledována. Níže uvedený formát systematicky přidává prefix s číslem iterace a názvem aktuálního kroku, což ti umožní filtrovat log o několika tisících řádcích až na jedinou sekvenci, která selhala. Akce přicházejí jako objekty z computer_call se stejnými poli jako v tvém handleru (x, y, scroll_x, keys…). Všimni si zpracování akce type: zaznamenáváme pouze délku zadaného textu, nikdy jeho obsah. Pokud agent vyplňuje přihlašovací formulář a píše heslo, platí zde bez výjimky pravidlo z předchozí lekce.

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())  # filtr z lekce 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Loguje akci z 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":
            # Nikdy samotný text: pouze jeho délka
            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())

Úroveň 2: Rozhodnutí modelu

Loguj, co model říká o svých volbách, abys pochopil, proč vybral konkrétní akci. Kliknutí na neočekávané souřadnice samo o nic neznamená; ve spojení s větou, která mu předcházela – „tlačítko odeslat se zdá být skryté za bannerem cookies“ – se stává diagnózou. Text je zkrácen na dvě stě znaků, což bohatě stačí k pochopení záměru, aniž by došlo k explozi objemu souboru. V odpovědi API Responses existují dva zdroje textu. Průběžné zprávy, které model napíše před provedením akce, mají phase: "commentary", zatímco konečná odpověď má phase: "final_answer". A pokud používaný model podporuje shrnutí úvah, získáš je jejich vyžádáním (reasoning={"summary": "auto"}): přicházejí v prvcích typu reasoning.

Spotřeba tokenů se loguje ve stejném tempu a zaslouží si pozornost: i při použití previous_response_id jsou všechny vstupní tokeny z předchozích odpovědí v řetězci znovu fakturovány jako vstup, včetně snímků obrazovky. Cena jednoho cyklu tedy s prodlužováním relace roste.

def log_model_response(response, iteration: int):
    """Loguje poznámky, shrnutí a volání z odpovědi (kromě obrázků)."""
    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)

    # Spotřebované tokeny
    logger.info(
        "[iter=%d] TOKENS: in=%d out=%d",
        iteration, response.usage.input_tokens, response.usage.output_tokens,
    )

Úroveň 3: Snímky obrazovky

Ukládej snímky obrazovky pro následnou analýzu chyb, ale hlídej si místo na disku: jeden PNG snímek často váží několik set kilobajtů a dlouhé workflow jich vyprodukuje stovky. Níže uvedená třída tento problém řeší jednoduchou rotací. Název souboru začíná časovým razítkem, což zarovnává abecední pořadí s chronologickým; třídění v metodě _cleanup pak stačí k identifikaci nejstarších snímků a jejich smazání, dokud počet neklesne pod strop sto souborů. Pole label ti umožňuje annotovat zajímavé momenty, například error nebo before_validation, a rychle je najít ve složce.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Ukládá snímky obrazovky s rotací."""

    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 = ""):
        """Uloží snímek obrazovky s popisným názvem."""
        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):
        """Smaže staré snímky obrazovky."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Metriky ke sledování

Úspěšnost
na workflow
Průměrná
doba trvání kroku
Náklady
v tocích na provedení
Chyby
podle typu a frekvence

Tyto čtyři ukazatele mají hodnotu pouze při porovnání s sebou samými v čase: pokles úspěšnosti workflow z devadesáti pěti na osmdesát procent ti řekne, že se rozhraní posunulo, dlouho before než si stěžuje první uživatel. Implementuj proto sběrač metrik připojený ke každému provedení. Datová třída WorkflowMetrics akumuluje tokeny iteraci po iteraci, sleduje chyby s jejich krokem a časovým razítkem a vystavuje dvě vypočítané vlastnosti: duration (doba trvání), která funguje, i když workflow ještě není dokončeno, a odhad nákladů založený na ceníku používaného modelu, který vezmeš ze stránky s cenami OpenAI, místo abys ho natvrdo zakódoval. Metoda summary vytvoří kompaktní slovník, který archivuješ při každém provedení.

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

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

@dataclass
class WorkflowMetrics:
    """Shromažďuje metriky pro workflow."""
    workflow_id: str
    input_price_per_million: float  # ceník pro používaný model
    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:
        # Odhad: ukládání promptů do cache a hostované prostředí se nepočítají
        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}",
        }

Monitorovací dashboard

Pro monitorování v reálném čase posílej metriky do monitorovací služby, místo aby spaly v souboru. Níže uvedená funkce odešle souhrn s časovým razítkem na HTTP endpoint se dvěma opatřeními, která jsou stejně důležitá jako samotné odeslání: maximální prodleva pět sekund a zachycená výjimka, která se spokojí s warningem. Nedostupný sběrač metrik nesmí nikdy shodit workflow, které pozoruje – opak by byl definicí kontraproduktivního dohledu.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Odešle metriky do monitorovací služby."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # requests sám nastaví hlavičku JSON
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Chyba odesílání metrik: {e}")

Automatická upozornění

Dashboard, který nikdo nesleduje, je jen archiv. Nakonfiguruj proto upozornění založená na prahových hodnotách, aby se anomálie dostala k tobě. Čtyři zde uvedené podmínky pokrývají klasické drifty: náklady vyšší než dva dolary, doba trvání přesahující tři minuty, více než třicet iterací nebo více než dvě chyby ve stejném provedení. Tyto hodnoty jsou výchozími body, nikoliv pravdami: kalibruj je na měřeních z vlastních úspěšných provedení a umísti práh dobře nad svůj pozorovaný medián. Upozornění, které se spustí každý den, bude druhý týden ignorováno.

def check_alerts(metrics: WorkflowMetrics):
    """Kontroluje prahové hodnoty a spouští upozornění."""
    alerts = []

    if metrics.estimated_cost_usd > 2.0:
        alerts.append(f"Vysoké náklady: ${metrics.estimated_cost_usd:.2f}")

    if metrics.duration_seconds > 180:
        alerts.append(f"Nadměrná doba trvání: {metrics.duration_seconds:.0f}s")

    if metrics.iterations > 30:
        alerts.append(f"Příliš mnoho iterací: {metrics.iterations}")

    if len(metrics.errors) > 2:
        alerts.append(f"Více chyb: {len(metrics.errors)}")

    for alert in alerts:
        logger.warning(f"UPOZORNĚNÍ: {alert}")
        # Odeslat oznámení (e-mail, Slack atd.)

    return alerts

Zvykni si volat check_alerts hned po finalize a poté push_metrics: získáš archivovanou stopu při každém provedení, signál odeslaný na dashboard a oznámení pouze tehdy, když si něco zaslouží tvou pozornost.

Klíčové poznatky

  • Loguj akce, zprávy a shrnutí modelu a snímky obrazovky na třech oddělených úrovních
  • Sleduj míru úspěšnosti, dobu trvání, náklady na tokeny a chyby; řetězená historie je v každém cyklu znovu fakturována jako vstup
  • Implementuj rotaci snímků obrazovky, aby nedošlo k zaplnění disku
  • Nastav automatická upozornění na kritické prahové hodnoty
  • Nikdy neloguj citlivá data (hesla, tokeny, osobní údaje)