Monitoring en logboekregistratie
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van de Computer use-gids van OpenAI en de documentatie van de Responses API: logboekregistratie leest nu acties uit een
computer_callen elementen uitresponse.output(berichten met hunphase, reasoning-samenvattingen, calls), in plaats van detool_use-blokken van de API van Anthropic; de hard-coded prijzen voor Claude Sonnet zijn vervangen door de prijzen van het gebruikte model, en de verouderdedatetime.utcnow()(sinds Python 3.12) is vervangen doordatetime.now(timezone.utc). Bronnen: Computer use · Pricing.
Uw agent observeren in productie
Een Computer Use-agent in productie is een zwarte doos als u geen goede monitoring instelt. In tegenstelling tot een standaard API waar u verzoeken en antwoorden logt, moet u hier ook visuele acties, screenshots en de beslissingen van het model traceren. Het verschil is concreet: wanneer een workflow om 3 uur ‘s nachts mislukt, is de vraag die er toe doet niet “welke uitzondering werd opgeworpen”, maar “wat zag de agent en waarom klikte hij daar?”. Een logbestand dat die vraag niet beantwoordt, helpt u de volgende ochtend niet verder.
De drie niveaus van logboekregistratie
Instrumentatie bouwt daarom voort op drie complementaire lagen: wat de agent deed, wat hij dacht voordat hij het deed, en wat hij zag toen hij besloot. Elk schrijft naar een ander kanaal, omdat noch het volume, noch de nuttige levensduur hetzelfde is.
Niveau 1: Acties
Elke actie die door de agent wordt uitgevoerd, moet worden getraceerd. Het onderstaande formaat voorziet systematisch van een prefix met het iteratienummer en de naam van de huidige stap, zodat u een logbestand van enkele duizenden regels kunt filteren tot de enige reeks die fout ging. Acties komen binnen als objecten vanuit de computer_call, met dezelfde velden als in uw handler (x, y, scroll_x, keys…). Let op de afhandeling van de type-actie: we registreren de lengte van de ingevoerde tekst, nooit de inhoud zelf. Een agent die een inlogformulier invult, typt een wachtwoord in, en de regel uit de vorige les geldt hier zonder uitzondering.
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 uit les 12
logger.addHandler(handler)
def log_action(action, iteration: int, step: str = ""):
"""Logt een actie vanuit een 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":
# Nooit de tekst zelf: alleen de lengte
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())
Niveau 2: Modelbeslissingen
Log wat het model zegt over zijn keuzes om te begrijpen waarom hij een specifieke actie heeft gekozen. Een klik op onverwachte coördinaten betekent op zich niets; gepaard met de zin die eraan voorafging—“de verzendknop lijkt verborgen door de cookiebanner”—wordt het een diagnose. De tekst wordt ingekort tot tweehonderd tekens, meer dan genoeg om de intentie te begrijpen zonder het bestandsvolume te laten exploderen. Er bestaan twee bronnen van tekst in een Responses API-antwoord. Tussenberichten die het model schrijft voordat het handelt, dragen phase: "commentary", terwijl het eindantwoord phase: "final_answer" draagt. En als het gebruikte model reasoning-samenvattingen ondersteunt, krijgt u deze door ze aan te vragen (reasoning={"summary": "auto"}): ze komen binnen in elementen van het type reasoning.
Tokenverbruik wordt in hetzelfde tempo gelogd en verdient nauwlettende aandacht: zelfs met previous_response_id worden alle input-tokens van eerdere antwoorden in de keten opnieuw gefactureerd als input, screenshots inbegrepen. De kosten van een beurt nemen dus toe naarmate de sessie langer duurt.
def log_model_response(response, iteration: int):
"""Logt notities, samenvattingen en calls vanuit een response (exclusief afbeeldingen)."""
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)
# Verbruikte tokens
logger.info(
"[iter=%d] TOKENS: in=%d out=%d",
iteration, response.usage.input_tokens, response.usage.output_tokens,
)
Niveau 3: Screenshots
Sla screenshots op voor post-mortem debugging, maar let op uw schijfruimte: een PNG-opname weegt vaak enkele honderden kilobytes, en een lange workflow produceert er honderden. De onderstaande klasse lost dit op met eenvoudige rotatie. De bestandsnaam begint met een tijdstempel, waardoor de alfabetische volgorde overeenkomt met de chronologische volgorde; sorteren in _cleanup volstaat dan om de oudste opnames te identificeren en te verwijderen totdat we weer onder het plafond van honderd bestanden zakken. Het veld label stelt u in staat interessante momenten te annoteren, bijvoorbeeld error of before_validation, en ze in één oogopslag te herkennen in de map.
from datetime import datetime, timezone
from pathlib import Path
class ScreenshotLogger:
"""Slaat screenshots op met rotatie."""
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 = ""):
"""Slaat een screenshot op met een beschrijvende naam."""
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):
"""Verwijdert oude screenshots."""
files = sorted(self.base_dir.glob("*.png"))
while len(files) > self.max_files:
files[0].unlink()
files.pop(0)
Te monitoren metrieken
Deze vier indicatoren zijn alleen waardevol wanneer ze in de tijd met zichzelf worden vergeleken: een workflow die daalt van vijfennegentig naar tachtig procent succes vertelt u dat een interface is verschoven, lang voordat de eerste gebruiker klaagt. Implementeer daarom een metriekverzamelaar die aan elke uitvoering is gekoppeld. De dataclass WorkflowMetrics accumuleert tokens iteratie na iteratie, houdt fouten bij met hun stap en tijdstempel, en exposeert twee berekende eigenschappen: duur, wat werkt zelfs als de workflow nog niet is voltooid, en een kostenschatting gebaseerd op de prijzen van het gebruikte model, die u haalt van de OpenAI-prijslijst in plaats van hard-coding. De methode summary produceert het compacte dictionary dat u bij elke uitvoering archiveert.
from dataclasses import dataclass, field
from datetime import datetime, timezone
def now() -> datetime:
return datetime.now(timezone.utc)
@dataclass
class WorkflowMetrics:
"""Verzamelt metrieken voor een workflow."""
workflow_id: str
input_price_per_million: float # prijzen voor het gebruikte 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:
# Schatting: prompt caching en een gehoste omgeving worden niet meegeteld
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}",
}
Monitoringdashboard
Voor realtime monitoring stuurt u metrieken naar een monitoringdienst in plaats van ze in een bestand te laten slapen. De onderstaande functie post de voorziene samenvatting naar een HTTP-eindpunt, met twee voorzorgsmaatregelen die even belangrijk zijn als het verzenden zelf: een maximale vertraging van vijf seconden, en een afgevangen uitzondering die genoegen neemt met een waarschuwing. Een niet-beschikbare metriekverzamelaar mag nooit de workflow neerhalen die hij observeert; het tegenovergestelde zou de definitie zijn van contraproductief toezicht.
import requests # pip install requests
def push_metrics(metrics: WorkflowMetrics, endpoint: str):
"""Verstuurt metrieken naar een monitoringdienst."""
payload = metrics.summary()
payload["timestamp"] = now().isoformat()
try:
requests.post(
endpoint,
json=payload, # requests stelt de JSON-header zelf in
timeout=5,
)
except requests.RequestException as e:
logger.warning(f"Metrics push error: {e}")
Automatische waarschuwingen
Een dashboard dat niemand bekijkt, is slechts een archief. Configureer daarom waarschuwingen op basis van drempelwaarden zodat de anomalie naar u toe komt. De vier hier behouden voorwaarden dekken klassieke afwijkingen: een kostenpost hoger dan twee dollar, een duur die drie minuten overschrijdt, meer dan dertig iteraties, of meer dan twee fouten in dezelfde uitvoering. Deze waarden zijn startpunten, geen waarheden: kalibreer ze op metingen van uw eigen succesvolle uitvoeringen, waarbij u de drempel ruim boven uw waargenomen mediaan plaatst. Een waarschuwing die elke dag afgaat, wordt in de tweede week genegeerd.
def check_alerts(metrics: WorkflowMetrics):
"""Controleert drempelwaarden en activeert waarschuwingen."""
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}")
# Verzend melding (e-mail, Slack, etc.)
return alerts
Maak er een gewoonte van om check_alerts direct na finalize aan te roepen, gevolgd door push_metrics: u krijgt bij elke uitvoering een gearchiveerd spoor, een signaal naar het dashboard, en alleen een melding wanneer iets uw aandacht verdient.
Belangrijkste punten
- Log acties, modelberichten en samenvattingen, en opnames op drie aparte niveaus
- Monitor succespercentage, duur, tokenkosten en fouten; de gekoppelde geschiedenis wordt elke beurt opnieuw als input gefactureerd
- Implementeer screenshot-rotatie om schijfverzadiging te voorkomen
- Stel automatische waarschuwingen in op kritieke drempelwaarden
- Log nooit gevoelige gegevens (wachtwoorden, tokens, persoonsgegevens)