Salt la conținutul principal
Română— Alege o limbă
Meniu

Monitorizare și jurnalizare

Lecția 13 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Observarea agentului în producție
  2. Cele trei niveluri de jurnalizare
  3. Metrici de monitorizat
  4. Panou de monitorizare
  5. Alerte automate
  6. Puncte cheie

Lecție actualizată la 3 noiembrie 2026 pe baza ghidului Computer use de la OpenAI și a documentației API Responses: jurnalizarea citește acum acțiunile dintr-un computer_call și elementele din response.output (mesaje cu phase-ul lor, rezumate de raționament, apeluri), în loc de blocurile tool_use din API-ul Anthropic; prețurile hard-codate pentru Claude Sonnet sunt înlocuite cu prețurile modelului utilizat, iar metoda depreciată datetime.utcnow() (din Python 3.12) este înlocuită cu datetime.now(timezone.utc). Surse: Computer use · Pricing.

Observarea agentului în producție

Un agent Computer Use aflat în producție este o cutie neagră dacă nu configurați o monitorizare adecvată. Spre deosebire de un API standard unde jurnalizați cererile și răspunsurile, aici trebuie să urmăriți și acțiunile vizuale, capturile de ecran și deciziile modelului. Diferența este concretă: când un flux de lucru eșuează la ora 3 dimineața, întrebarea care contează nu este „ce excepție a fost aruncată“, ci „ce a văzut agentul și de ce a dat clic acolo?“. Un jurnal care nu răspunde la această întrebare nu vă va fi de niciun ajutor a doua zi dimineață.

Cele trei niveluri de jurnalizare

Instrumentarea se bazează, așadar, pe trei straturi complementare: ce a făcut agentul, ce a gândit înainte de a acționa și ce a văzut când a luat decizia. Fiecare scrie într-un canal diferit, deoarece nici volumul, nici durata de viață utilă nu sunt aceleași.

Nivelul 1: Acțiuni

Fiecare acțiune executată de agent trebuie urmărită. Formatul de mai jos prefixează sistematic numărul iterației și numele pasului curent, permițându-vă să filtrați un jurnal de câteva mii de linii până la singura secvență care a mers prost. Acțiunile sosesc ca obiecte din computer_call, cu aceleași câmpuri ca în handler-ul dumneavoastră (x, y, scroll_x, keys…). Rețineți gestionarea acțiunii type: înregistrăm lungimea textului introdus, niciodată conținutul său. Un agent care completează un formular de autentificare tastează o parolă, iar regula din lecția anterioară se aplică aici fără excepție.

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())  # filtru din lecția 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Jurnalizează o acțiune dintr-un 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":
            # Niciodată textul propriu-zis: doar lungimea sa
            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())

Nivelul 2: Deciziile modelului

Jurnalizați ce spune modelul despre alegerile sale pentru a înțelege de ce a selectat o acțiune specifică. Un clic la coordonate neașteptate nu înseamnă nimic de unul singur; asociat cu propoziția care l-a precedat – „butonul de submit pare ascuns de banner-ul cookie“ – devine un diagnostic. Textul este trunchiat la două sute de caractere, suficient pentru a înțelege intenția fără a explodea volumul fișierului. Există două surse de text într-un răspuns API Responses. Mesajele intermediare pe care modelul le scrie înainte de a acționa poartă phase: "commentary", în timp ce răspunsul final poartă phase: "final_answer". Și dacă modelul utilizat suportă rezumate de raționament, le obțineți solicitându-le (reasoning={"summary": "auto"}): acestea sosesc în elemente de tip reasoning.

Consumul de tokeni este jurnalizat în același ritm și merită o atenție deosebită: chiar și cu previous_response_id, toți tokenii de input din răspunsurile anterioare din lanț sunt refacturați ca input, inclusiv capturile de ecran. Costul unei runde crește, așadar, pe măsură ce sesiunea se lungesc.

def log_model_response(response, iteration: int):
    """Jurnalizează note, rezumate și apeluri dintr-un răspuns (excluzând imaginile)."""
    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)

    # Tokeni consumați
    logger.info(
        "[iter=%d] TOKENS: in=%d out=%d",
        iteration, response.usage.input_tokens, response.usage.output_tokens,
    )

Nivelul 3: Capturi de ecran

Salvați capturile de ecran pentru depanarea post-mortem, dar aveți grijă la spațiul pe disc: o captură PNG cântărește adesea câteva sute de kilobyți, iar un flux de lucru lung produce sute de astfel de fișiere. Clasa de mai jos rezolvă această problemă printr-o rotație simplă. Numele fișierului începe cu un timestamp, aliniind ordinea alfabetică cu cea cronologică; sortarea din _cleanup este apoi suficientă pentru a identifica cele mai vechi capturi și a le șterge până se revine sub plafonul de o sută de fișiere. Câmpul label vă permite să adnotați momente interesante, de exemplu error sau before_validation, și să le identificați dintr-o privire în dosar.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Salvează capturile de ecran cu rotație."""

    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 = ""):
        """Salvează o captură de ecran cu un nume descriptiv."""
        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):
        """Șterge capturile de ecran vechi."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Metrici de monitorizat

Rată de succes
per flux de lucru
Durată medie
per pas
Cost
în tokeni per execuție
Erori
după tip și frecvență

Acești patru indicatori sunt valoroși doar atunci când sunt comparați cu ei înșiși în timp: un flux de lucru care scade de la nouăzeci și cinci la optzeci la sută succes vă spune că o interfață s-a mutat, cu mult înainte ca primul utilizator să se plângă. Prin urmare, implementați un colector de metrici atașat fiecărei execuții. Dataclass-ul WorkflowMetrics acumulează tokenii iterație după iterație, ține evidența erorilor cu pasul și timestamp-ul lor și expune două proprietăți calculate: durata, care funcționează chiar dacă fluxul de lucru nu este încă terminat, și o estimare a costului bazată pe prețurile modelului utilizat, pe care le luați de pe pagina de prețuri OpenAI în loc să le hard-codați. Metoda summary produce dicționarul compact pe care îl veți arhiva la fiecare execuție.

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

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

@dataclass
class WorkflowMetrics:
    """Colectează metrici pentru un flux de lucru."""
    workflow_id: str
    input_price_per_million: float  # prețurile pentru modelul utilizat
    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:
        # Estimare: caching-ul prompt-urilor și un mediu găzduit nu sunt contorizate
        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}",
        }

Panou de monitorizare

Pentru monitorizarea în timp real, trimiteți metricile către un serviciu de monitorizare în loc să le lăsați să doarmă într-un fișier. Funcția de mai jos postează rezumatul cu timestamp către un endpoint HTTP, cu două precauții care contează la fel de mult ca trimiterea propriu-zisă: o întârziere maximă de cinci secunde și o excepție prinsă care se mulțumește cu o avertizare. Un colector de metrici indisponibil nu trebuie niciodată să dărâme fluxul de lucru pe care îl observă – contrariul ar fi definiția unei superviziuni contraproductive.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Trimite metricile către un serviciu de monitorizare."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # requests setează singur header-ul JSON
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Eroare la trimiterea metricilor: {e}")

Alerte automate

Un panou pe care nimeni nu îl privește este doar o arhivă. Prin urmare, configurați alerte bazate pe praguri astfel încât anomalia să vină la dumneavoastră. Cele patru condiții reținute aici acoperă devierile clasice: un cost mai mare de doi dolari, o durată care depășește trei minute, mai mult de treizeci de iterații sau mai mult de două erori în aceeași execuție. Aceste valori sunt puncte de plecare, nu adevăruri absolute: calibrați-le pe măsurători din propriile execuții reușite, plasând pragul mult peste mediana observată. O alertă care se declanșează în fiecare zi va fi ignorată începând cu a doua săptămână.

def check_alerts(metrics: WorkflowMetrics):
    """Verifică pragurile și declanșează alerte."""
    alerts = []

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

    if metrics.duration_seconds > 180:
        alerts.append(f"Durată excesivă: {metrics.duration_seconds:.0f}s")

    if metrics.iterations > 30:
        alerts.append(f"Prea multe iterații: {metrics.iterations}")

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

    for alert in alerts:
        logger.warning(f"ALERTĂ: {alert}")
        # Trimiteți notificarea (email, Slack, etc.)

    return alerts

Obişnuiți-vă să apelați check_alerts imediat după finalize, apoi push_metrics: obțineți o urmă arhivată la fiecare execuție, un semnal trimis panoului de control și o notificare doar când ceva merită atenția dumneavoastră.

Puncte cheie

  • Jurnalizați acțiunile, mesajele și rezumatele modelului, precum și capturile pe trei niveluri separate
  • Monitorizați rata de succes, durata, costul în tokeni și erorile; istoricul înlănțuit este refacturat ca input la fiecare rundă
  • Implementați rotația capturilor de ecran pentru a evita saturarea discului
  • Configurați alerte automate pe praguri critice
  • Nu jurnalizați niciodată date sensibile (parole, tokeni, date personale)