Monitoraggio e registrazione
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della guida Computer use di OpenAI e della documentazione delle API Responses: la registrazione ora legge le azioni da un
computer_calle gli elementi daresponse.output(messaggi con il lorophase, riepiloghi del ragionamento, chiamate), invece dei blocchitool_usedelle API di Anthropic; il prezzo hardcoded di Claude Sonnet è sostituito dal prezzo del modello in uso, e il deprecatodatetime.utcnow()(dalla Python 3.12) è sostituito dadatetime.now(timezone.utc). Fonti: Computer use · Prezzi.
Osservare il tuo agente in produzione
Un agente Computer Use in produzione è una scatola nera se non imposti un monitoraggio adeguato. A differenza di un’API standard dove registri richieste e risposte, qui devi anche tracciare le azioni visive, gli screenshot e le decisioni del modello. La differenza è concreta: quando un flusso di lavoro fallisce alle 3 del mattino, la domanda importante non è “quale eccezione è stata sollevata”, ma “cosa ha visto l’agente e perché ha cliccato lì?”. Un log che non risponde a questa domanda non ti sarà utile la mattina dopo.
I tre livelli di registrazione
La strumentazione si basa quindi su tre livelli complementari: cosa ha fatto l’agente, cosa ha pensato prima di farlo e cosa ha visto mentre decideva. Ognuno scrive su un canale diverso perché né il volume né la durata utile sono gli stessi.
Livello 1: Azioni
Ogni azione eseguita dall’agente deve essere tracciata. Il formato sottostante antepone sistematicamente il numero di iterazione e il nome del passaggio corrente, permettendoti di filtrare un log di diverse migliaia di righe fino alla singola sequenza andata male. Le azioni arrivano come oggetti da un computer_call, con gli stessi campi del tuo gestore (x, y, scroll_x, keys…). Nota la gestione dell’azione type: registriamo la lunghezza del testo inserito, mai il suo contenuto. Un agente che compila un modulo di login digita una password e la regola della lezione precedente si applica qui senza eccezioni.
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()) # filtro dalla lezione 12
logger.addHandler(handler)
def log_action(action, iteration: int, step: str = ""):
"""Registra un'azione da 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":
# Mai il testo stesso: solo la sua lunghezza
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())
Livello 2: Decisioni del modello
Registra ciò che il modello dice sulle sue scelte per capire perché ha selezionato un’azione specifica. Un clic a coordinate inaspettate non significa nulla di per sé; abbinato alla frase che lo ha preceduto — «il pulsante di invio sembra nascosto dal banner dei cookie» — diventa una diagnosi. Il testo viene troncato a duecento caratteri, più che sufficienti per cogliere l’intento senza far esplodere il volume del file. Esistono due fonti di testo in una risposta delle API Responses. I messaggi intermedi che il modello scrive prima di agire portano phase: "commentary", mentre la risposta finale porta phase: "final_answer". E se il modello in uso supporta i riepiloghi del ragionamento, li ottieni richiedendoli (reasoning={"summary": "auto"}): arrivano in elementi di tipo reasoning.
Il consumo di token viene registrato allo stesso ritmo e merita molta attenzione: anche con previous_response_id, tutti i token di input delle risposte precedenti nella catena vengono rifatturati come input, screenshot inclusi. Il costo di un turno aumenta quindi man mano che la sessione si prolunga.
def log_model_response(response, iteration: int):
"""Registra note, riepiloghi e chiamate da una risposta (escluse le immagini)."""
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)
# Token consumati
logger.info(
"[iter=%d] TOKENS: in=%d out=%d",
iteration, response.usage.input_tokens, response.usage.output_tokens,
)
Livello 3: Screenshot
Salva gli screenshot per il debug post-mortem, ma fai attenzione allo spazio su disco: un’acquisizione PNG pesa spesso diverse centinaia di kilobyte e un flusso di lavoro lungo ne produce centinaia. La classe sottostante risolve il problema con una semplice rotazione. Il nome del file inizia con un timestamp, allineando l’ordine alfabetico a quello cronologico; l’ordinamento in _cleanup è quindi sufficiente per identificare le acquisizioni più vecchie ed eliminarle fino a scendere sotto il tetto di cento file. Il campo label ti permette di annotare momenti interessanti, ad esempio error o before_validation, e individuarli a colpo d’occhio nella cartella.
from datetime import datetime, timezone
from pathlib import Path
class ScreenshotLogger:
"""Salva screenshot con rotazione."""
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 = ""):
"""Salva uno screenshot con un nome descrittivo."""
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):
"""Elimina gli screenshot vecchi."""
files = sorted(self.base_dir.glob("*.png"))
while len(files) > self.max_files:
files[0].unlink()
files.pop(0)
Metriche da monitorare
Questi quattro indicatori hanno valore solo se confrontati con se stessi nel tempo: un flusso di lavoro che scende dal novantacinque all’ottanta percento di successo ti dice che un’interfaccia si è spostata, ben prima che il primo utente si lamenti. Implementa quindi un raccoglitore di metriche allegato a ogni esecuzione. La dataclass WorkflowMetrics accumula i token iterazione dopo iterazione, tiene traccia degli errori con il loro passaggio e timestamp, ed espone due proprietà calcolate: la durata, che funziona anche se il flusso di lavoro non è ancora terminato, e una stima del costo basata sul prezzo del modello in uso, che prendi dalla pagina dei prezzi di OpenAI invece di hardcodarla. Il metodo summary produce il dizionario compatto che archiverai a ogni esecuzione.
from dataclasses import dataclass, field
from datetime import datetime, timezone
def now() -> datetime:
return datetime.now(timezone.utc)
@dataclass
class WorkflowMetrics:
"""Raccoglie metriche per un flusso di lavoro."""
workflow_id: str
input_price_per_million: float # prezzo per il modello in uso
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:
# Stima: caching dei prompt e ambiente ospitato non contati
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}",
}
Dashboard di monitoraggio
Per il monitoraggio in tempo reale, invia le metriche a un servizio di monitoraggio invece di lasciarle dormire in un file. La funzione sottostante invia il riepilogo con timestamp a un endpoint HTTP, con due precauzioni importanti quanto l’invio stesso: un ritardo massimo di cinque secondi e un’eccezione catturata che si limita a un warning. Un raccoglitore di metriche non disponibile non deve mai far crollare il flusso di lavoro che osserva: il contrario sarebbe la definizione di una supervisione controproducente.
import requests # pip install requests
def push_metrics(metrics: WorkflowMetrics, endpoint: str):
"""Invia metriche a un servizio di monitoraggio."""
payload = metrics.summary()
payload["timestamp"] = now().isoformat()
try:
requests.post(
endpoint,
json=payload, # requests imposta l'header JSON da solo
timeout=5,
)
except requests.RequestException as e:
logger.warning(f"Metrics push error: {e}")
Avvisi automatici
Una dashboard che nessuno guarda è solo un archivio. Configura quindi degli avvisi basati su soglie in modo che l’anomalia arrivi da te. Le quattro condizioni qui riportate coprono le derive classiche: un costo superiore a due dollari, una durata superiore a tre minuti, più di trenta iterazioni o più di due errori nella stessa esecuzione. Questi valori sono punti di partenza, non verità: calibrarli sulle misurazioni delle tue esecuzioni di successo, posizionando la soglia ben sopra la mediana osservata. Un avviso che si attiva ogni giorno verrà ignorato dalla seconda settimana.
def check_alerts(metrics: WorkflowMetrics):
"""Controlla le soglie e attiva gli avvisi."""
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}")
# Invia notifica (email, Slack, ecc.)
return alerts
Prendi l’abitudine di chiamare check_alerts subito dopo finalize, poi push_metrics: ottieni una traccia archiviata a ogni esecuzione, un segnale inviato alla dashboard e una notifica solo quando qualcosa merita la tua attenzione.
Punti chiave
- Registra azioni, messaggi e riepiloghi del modello e acquisizioni su tre livelli separati
- Monitora il tasso di successo, la durata, il costo in token e gli errori; la cronologia concatenata viene rifatturata come input a ogni turno
- Implementa la rotazione degli screenshot per evitare di saturare il disco
- Imposta avvisi automatici su soglie critiche
- Non registrare mai dati sensibili (password, token, dati personali)