Monitorizare și jurnalizare
Pe această pagină
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 dinresponse.output(mesaje cuphase-ul lor, rezumate de raționament, apeluri), în loc de blocuriletool_usedin 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ă cudatetime.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
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)