Ir al contenido principal
Español— Elegir un idioma
Menú

Monitorización y registro

Lección 13 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Observación de tu agente en producción
  2. Los tres niveles de registro
  3. Métricas a monitorizar
  4. Panel de monitorización
  5. Alertas automáticas
  6. Puntos clave

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_call y los elementos desde response.output (mensajes con su phase, resúmenes de razonamiento, llamadas), en lugar de los bloques tool_use de la API de Anthropic; la tarifa fija de Claude Sonnet se sustituye por el precio del modelo en uso, y el obsoleto datetime.utcnow() (desde Python 3.12) se reemplaza por datetime.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

Tasa de
éxito por flujo
Duración
media por paso
Coste
en tokens por ejecución
Errores
por tipo y frecuencia

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)