Monitorización y registro
En esta página
Lección actualizada el 3 de noviembre de 2026 según la guía Computer use de OpenAI y la documentación de la API de Responses: el registro lee ahora las acciones desde un
computer_cally los elementos desderesponse.output(mensajes con suphase, resúmenes de razonamiento, llamadas), en lugar de los bloquestool_usede la API de Anthropic; la tarifa fija de Claude Sonnet se sustituye por el precio del modelo en uso, y el obsoletodatetime.utcnow()(desde Python 3.12) se reemplaza pordatetime.now(timezone.utc). Fuentes: Computer use · Precios.
Observación de tu agente en producción
Un agente de Computer Use en producción es una caja negra si no configuras una monitorización adecuada. A diferencia de una API estándar donde registras peticiones y respuestas, aquí debes rastrear también las acciones visuales, las capturas de pantalla y las decisiones del modelo. La diferencia es concreta: cuando un flujo de trabajo falla a las 3 de la mañana, la pregunta importante no es «qué excepción se ha lanzado», sino «qué ha visto el agente y por qué ha hecho clic ahí?». Un registro que no responda a esa pregunta no te servirá de nada a la mañana siguiente.
Los tres niveles de registro
La instrumentación se basa, por tanto, en tres capas complementarias: lo que el agente ha hecho, lo que ha pensado antes de hacerlo y lo que ha visto al decidir. Cada una escribe en un canal distinto porque ni el volumen ni la vida útil son los mismos.
Nivel 1: Acciones
Debes rastrear cada acción ejecutada por el agente. El formato siguiente antepone sistemáticamente el número de iteración y el nombre del paso actual, lo que te permite filtrar un registro de varios miles de líneas hasta reducirlo a la única secuencia que ha fallado. Las acciones llegan como objetos desde computer_call, con los mismos campos que en tu gestor (x, y, scroll_x, keys…). Observa el tratamiento de la acción type: registramos la longitud del texto introducido, nunca su contenido. Un agente que rellena un formulario de inicio de sesión escribe una contraseña, y la regla de la lección anterior se aplica aquí sin excepción.
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 de la lección 12
logger.addHandler(handler)
def log_action(action, iteration: int, step: str = ""):
"""Registra una acción procedente de 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":
# Nunca el texto en sí: solo su longitud
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())
Nivel 2: Decisiones del modelo
Registra lo que el modelo dice sobre sus elecciones para entender por qué ha seleccionado una acción concreta. Un clic en unas coordenadas inesperadas no significa nada por sí solo; paired con la frase que lo precedió —«el botón de enviar parece estar oculto por el banner de cookies»— se convierte en un diagnóstico. El texto se trunca a doscientos caracteres, más que suficiente para captar la intención sin disparar el volumen del archivo. Existen dos fuentes de texto en una respuesta de la API de Responses. Los mensajes intermedios que el modelo escribe antes de actuar llevan phase: "commentary", mientras que la respuesta final lleva phase: "final_answer". Y si el modelo en uso admite resúmenes de razonamiento, los obtienes solicitándolos (reasoning={"summary": "auto"}): llegan en elementos de tipo reasoning.
El consumo de tokens se registra al mismo ritmo y merece una atención estrecha: incluso con previous_response_id, todos los tokens de entrada de las respuestas anteriores en la cadena se vuelven a facturar como entrada, incluidas las capturas de pantalla. El coste de un turno aumenta, por tanto, a medida que se alarga la sesión.
def log_model_response(response, iteration: int):
"""Registra notas, resúmenes y llamadas de una respuesta (excluyendo imágenes)."""
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)
# Tokens consumidos
logger.info(
"[iter=%d] TOKENS: in=%d out=%d",
iteration, response.usage.input_tokens, response.usage.output_tokens,
)
Nivel 3: Capturas de pantalla
Guarda las capturas de pantalla para la depuración post-mortem, pero vigila tu espacio en disco: una captura en PNG suele pesar varios cientos de kilobytes, y un flujo de trabajo largo produce cientos de ellas. La clase siguiente resuelve esto con una rotación simple. El nombre del archivo comienza con una marca de tiempo, alineando el orden alfabético con el cronológico; la ordenación en _cleanup basta entonces para identificar las capturas más antiguas y eliminarlas hasta volver a bajar del techo de cien archivos. El campo label te permite anotar momentos interesantes, por ejemplo error o before_validation, y localizarlos de un vistazo en la carpeta.
from datetime import datetime, timezone
from pathlib import Path
class ScreenshotLogger:
"""Guarda capturas de pantalla con rotación."""
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 = ""):
"""Guarda una captura con un nombre descriptivo."""
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 capturas antiguas."""
files = sorted(self.base_dir.glob("*.png"))
while len(files) > self.max_files:
files[0].unlink()
files.pop(0)
Métricas a monitorizar
Estos cuatro indicadores solo tienen valor cuando se comparan consigo mismos a lo largo del tiempo: que un flujo de trabajo baje del noventa y cinco al ochenta por ciento de éxito te indica que una interfaz ha cambiado, mucho antes de que el primer usuario se queje. Implementa, por tanto, un recopilador de métricas adjunto a cada ejecución. La clase de datos WorkflowMetrics acumula tokens iteración tras iteración, lleva la cuenta de los errores con su paso y marca de tiempo, y expone dos propiedades calculadas: la duración, que funciona incluso si el flujo no ha terminado aún, y una estimación de coste basada en la tarifa del modelo en uso, que tomas de la página de precios de OpenAI en lugar de hardcodearla. El método summary produce el diccionario compacto que archivarás en cada ejecución.
from dataclasses import dataclass, field
from datetime import datetime, timezone
def now() -> datetime:
return datetime.now(timezone.utc)
@dataclass
class WorkflowMetrics:
"""Recopila métricas para un flujo de trabajo."""
workflow_id: str
input_price_per_million: float # tarifa del modelo en 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:
# Estimación: no se cuentan el caché de prompts ni un entorno alojado
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}",
}
Panel de monitorización
Para la monitorización en tiempo real, envía las métricas a un servicio de monitorización en lugar de dejarlas durmiendo en un archivo. La función siguiente publica el resumen con marca de tiempo en un punto de acceso HTTP, con dos precauciones que importan tanto como el propio envío: un retraso máximo de cinco segundos y una excepción capturada que se conforma con una advertencia. Un recopilador de métricas no disponible nunca debe tumbar el flujo de trabajo que observa; lo contrario sería la definición de una supervisión contraproducente.
import requests # pip install requests
def push_metrics(metrics: WorkflowMetrics, endpoint: str):
"""Envía métricas a un servicio de monitorización."""
payload = metrics.summary()
payload["timestamp"] = now().isoformat()
try:
requests.post(
endpoint,
json=payload, # requests establece la cabecera JSON él mismo
timeout=5,
)
except requests.RequestException as e:
logger.warning(f"Metrics push error: {e}")
Alertas automáticas
Un panel que nadie mira es solo un archivo. Configura, por tanto, alertas basadas en umbrales para que la anomalía venga a ti. Las cuatro condiciones retenidas aquí cubren desviaciones clásicas: un coste superior a dos dólares, una duración que excede los tres minutos, más de treinta iteraciones o más de dos errores en la misma ejecución. Estos valores son puntos de partida, no verdades: calíbralos con mediciones de tus propias ejecuciones exitosas, situando el umbral muy por encima de tu mediana observada. Una alerta que se dispara todos los días será ignorada a la segunda semana.
def check_alerts(metrics: WorkflowMetrics):
"""Comprueba umbrales y activa alertas."""
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}")
# Enviar notificación (correo, Slack, etc.)
return alerts
Acostúmbrate a llamar a check_alerts justo después de finalize y luego a push_metrics: obtendrás un rastro archivado en cada ejecución, una señal enviada al panel y una notificación solo cuando algo merezca tu atención.
Puntos clave
- Registra acciones, mensajes y resúmenes del modelo, y capturas en tres niveles separados
- Monitoriza la tasa de éxito, la duración, el coste en tokens y los errores; el historial encadenado se vuelve a facturar como entrada en cada turno
- Implementa la rotación de capturas de pantalla para evitar saturar el disco
- Configura alertas automáticas sobre umbrales críticos
- Nunca registres datos sensibles (contraseñas, tokens, datos personales)