Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Nadzor in beleženje dogodkov

Lekcija 13 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Opazovanje vašega agenta v produkciji
  2. Tri ravni beleženja
  3. Metrike za nadzor
  4. Nadzorna plošča
  5. Samodejna opozorila
  6. Ključne ugotovitve

Lekcija posodobljena 3. novembra 2026 na podlagi vodnika Computer use podjetja OpenAI in dokumentacije API-ja Responses: beleženje zdaj bere dejanja iz computer_call in elemente iz response.output (sporočila z njihovimi phase, povzetki razmišljanja, klici), namesto blokov tool_use iz API-ja Anthropic; vgrajene cene za Claude Sonnet so nadomeščene s cenami modela, ki je trenutno v uporabi, zastareli datetime.utcnow() (od Pythona 3.12 dalje) pa je nadomeščen z datetime.now(timezone.utc). Viri: Computer use · Cenik.

Opazovanje vašega agenta v produkciji

Agent Computer Use v produkciji je črna škatla, če ne vzpostavite ustreznega nadzora. Za razliko od standardnega API-ja, kjer beležite zahteve in odgovore, morate tukaj slediti tudi vizualnim dejanjem, posnetkom zaslona in odločitvam modela. Razlika je konkretna: ko se delovni tok pokvari ob 3. uri zjutraj, vprašanje, ki šteje, ni „katera izjema je bila sprožena”, temveč „kaj je agent videl in zakaj je kliknil tam?”. Dnevnik, ki na to vprašanje ne odgovori, vam naslednje jutro ne bo prav nič pomagal.

Tri ravni beleženja

Instrumentacija zato temelji na treh komplementarnih plasteh: kaj je agent storil, kaj je razmišljal pred tem in kaj je videl ob odločanju. Vsaka piše v drug kanal, saj niti obseg niti uporabna življenjska doba nista enaka.

1. raven: Dejanja

Slediti morate vsakemu dejanju, ki ga agent izvrši. Spodnji format sistematično doda predpono s številko iteracije in imenom trenutnega koraka, kar vam omogoča, da dnevnik z več tisoč vrsticami filtrirate na edino zaporedje, ki je šlo narobe. Dejanja prispejo kot objekti iz computer_call z istimi polji kot v vašem rokovanju (x, y, scroll_x, keys…). Bodite pozorni na obravnavo dejanja type: zabeležimo dolžino vnesenega besedila, nikoli pa njegove vsebine. Ko agent izpolnjuje prijavnico, vtipka geslo in tu brez izjeme velja pravilo iz prejšnje lekcije.

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 iz lekcije 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Zabeleži dejanje iz 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":
            # Nikoli samo besedilo: samo njegova dolžina
            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())

2. raven: Odločitve modela

Zabeležite, kaj model pove o svojih izbirah, da razumete, zakaj je izbral določeno dejanje. Klik na nepričakovanih koordinatah sam po sebi ne pomeni nič; v povezavi z stavkom, ki mu je precedil – „gumb za oddajo se zdi skrit za pasico s piškotki” – postane diagnoza. Besedilo je okrajšano na dvesto znakov, kar je več kot dovolj za razumevanje namena, ne da bi eksplodirala velikost datoteke. V odgovoru API-ja Responses obstajata dva vira besedila. Vmesna sporočila, ki jih model zapiše pred dejanjem, nosijo phase: "commentary", končni odgovor pa phase: "final_answer". In če model, ki ga uporabljate, podpira povzetke razmišljanja, jih dobite tako, da jih zahtevate (reasoning={"summary": "auto"}): prispejo v elementih tipa reasoning.

Poraba žetonov se beleži v istem tempu in zasluži si veliko pozornosti: tudi z previous_response_id se vsi vhodni žetoni iz prejšnjih odgovorov v verigi ponovno zaračunajo kot vhod, vključno s posnetki zaslona. Strošek kroga se zato povečuje, kot se podaljšuje seja.

def log_model_response(response, iteration: int):
    """Zabeleži opombe, povzetke in klice iz odgovora (brez slik)."""
    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)

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

3. raven: Posnetki zaslona

Shranite posnetke zaslona za naknadno odpravljanje napak, vendar pazite na prostor na disku: posnetek PNG pogosto tehta več sto kilobajtov, dolg delovni tok pa jih ustvari na stotine. Spodnji razred to reši s preprostim vrtenjem. Ime datoteke se začne s časovnim žigom, kar uskladi abecedni vrstni red s kronološkim; razvrščanje v _cleanup je nato dovolj za identifikacijo najstarejših posnetkov in njihov izbris, dokler se ne spustite pod zgornjo mejo sto datotek. Polje label vam omogoča označevanje zanimivih trenutkov, na primer error ali before_validation, in njihov hiter pregled v mapi.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Shranjuje posnetke zaslona z vrtenjem."""

    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 = ""):
        """Shrani posnetek zaslona z opisnim imenom."""
        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):
        """Izbriše stare posnetke zaslona."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Metrike za nadzor

Uspešnost
na delovni tok
Povprečno
trajanje na korak
Strošek
v žetonih na izvedbo
Napake
po vrsti in pogostosti

Ti štirje kazalniki so dragoceni le, če jih skozi čas primerjate same s seboj: padec uspešnosti delovnega toka z petindevetdeset na osemdeset odstotkov vam pove, da se je vmesnik premaknil, dolgo preden se pritoži prvi uporabnik. Zato implementirajte zbiralec metrik, pripet vsaki izvedbi. Podatkovni razred WorkflowMetrics kopiči žetone iteracijo za iteracijo, sledi napakam z njihovim korakom in časovnim žigom ter razkriva dva izračunana lastnosti: trajanje, ki deluje tudi, če delovni tok še ni končan, in oceno stroška na podlagi cenika modela, ki je v uporabi; tega vzamete s strani s cenami OpenAI, namesto da bi ga vgradili v kodo. Metoda summary ustvari kompakten slovar, ki ga boste arhivirali ob vsaki izvedbi.

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

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

@dataclass
class WorkflowMetrics:
    """Zbira metrike za delovni tok."""
    workflow_id: str
    input_price_per_million: float  # cenik za model v uporabi
    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:
        # Ocena: predpomnjenje pozivov in gostovano okolje nista šteta
        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}",
        }

Nadzorna plošča

Za nadzor v realnem času pošljite metrike storitvi za nadzor, namesto da bi jih pustile spati v datoteki. Spodnja funkcija objavi povzetek s časovnim žigom na končno točko HTTP, pri čemer upošteva dva previdnostna ukrepa, ki sta enako pomembna kot samo pošiljanje: največji zamik petih sekund in ujeto izjemo, ki se zadovolji z opozorilom. Nedostopen zbiralec metrik nikoli ne sme porušiti delovnega toka, ki ga opazuje – nasprotno bi bila opredelitev kontraproduktivnega nadzora.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Pošlje metrike storitvi za nadzor."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # requests sam nastavi glavo JSON
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Metrics push error: {e}")

Samodejna opozorila

Nadzorna plošča, ki je nihče ne gleda, je le arhiv. Zato konfigurirajte opozorila na podlagi pragov, da anomalija pride do vas. Štirje tukaj zadržani pogoji pokrivajo klasična odstopanja: strošek, višji od dveh dolarjev, trajanje, ki presega tri minute, več kot trideset iteracij ali več kot dve napaki v isti izvedbi. Te vrednosti so izhodišča, ne resnice: umerite jih na meritvah iz lastnih uspešnih izvedb in prag postavite dobro nad svojo opaženo mediano. Opozorilo, ki se sproži vsak dan, bo drug teden ignorirano.

def check_alerts(metrics: WorkflowMetrics):
    """Preveri pragove in sproži opozorila."""
    alerts = []

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

    if metrics.duration_seconds > 180:
        alerts.append(f"Excessive duration: {metrics.duration_seconds:.0f}s")

    if metrics.iterations > 30:
        alerts.append(f"Too many iterations: {metrics.iterations}")

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

    for alert in alerts:
        logger.warning(f"ALERT: {alert}")
        # Pošlji obvestilo (e-pošta, Slack itd.)

    return alerts

Naj vam pride v navado, da pokličete check_alerts takoj za finalize, nato pa še push_metrics: tako dobite arhivirano sled pri vsaki izvedbi, signal, poslan na nadzorno ploščo, in obvestilo le takrat, ko si nekaj zasluži vašo pozornost.

Ključne ugotovitve

  • Beležite dejanja, sporočila in povzetke modela ter posnetke na treh ločenih ravneh
  • Spremljajte stopnjo uspešnosti, trajanje, strošek žetonov in napake; verижna zgodovina se vsak krog ponovno zaračuna kot vhod
  • Implementirajte vrtenje posnetkov zaslona, da se izognete zapolnitvi diska
  • Vzpostavite samodejna opozorila na kritičnih pragovih
  • Nikoli ne beležite občutljivih podatkov (gesla, žetoni, osebni podatki)