Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Monitorização e registo de eventos

Aula 13 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Observar o seu agente em produção
  2. Os três níveis de registo
  3. Métricas a monitorizar
  4. Painel de monitorização
  5. Alertas automáticos
  6. Pontos-chave

Lição atualizada a 3 de novembro de 2026 com base no guia Computer use da OpenAI e na documentação da API Responses: o registo de eventos lê agora as ações de um computer_call e os elementos de response.output (mensagens com a sua phase, resumos de raciocínio, chamadas), em vez dos blocos tool_use da API da Anthropic; o preço fixo do Claude Sonnet foi substituído pelo preço do modelo em uso, e o método obsoleto datetime.utcnow() (desde o Python 3.12) foi substituído por datetime.now(timezone.utc). Fontes: Computer use · Preços.

Observar o seu agente em produção

Um agente Computer Use em produção é uma caixa negra se não configurar uma monitorização adequada. Ao contrário de uma API padrão, onde regista pedidos e respostas, aqui deve também rastrear ações visuais, capturas de ecrã e as decisões do modelo. A diferença é concreta: quando um fluxo de trabalho falha às 3 da manhã, a pergunta importante não é “que excecão foi levantada”, mas “o que é que o agente viu e por que razão clicou ali?”. Um registo que não responda a essa pergunta não o ajudará na manhã seguinte.

Os três níveis de registo

A instrumentação baseia-se, portanto, em três camadas complementares: o que o agente fez, o que pensou antes de o fazer e o que viu ao decidir. Cada uma escreve num canal diferente, pois nem o volume nem a duração útil são os mesmos.

Nível 1: Ações

Cada ação executada pelo agente deve ser rastreada. O formato abaixo antepõe sistematicamente o número da iteração e o nome do passo atual, permitindo filtrar um registo de vários milhares de linhas até à única sequência que falhou. As ações chegam como objetos de um computer_call, com os mesmos campos do seu manipulador (x, y, scroll_x, keys…). Note o tratamento da ação type: registamos o comprimento do texto introduzido, nunca o seu conteúdo. Um agente que preenche um formulário de login digita uma palavra-passe, e a regra da lição anterior aplica-se aqui sem exceção.

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 da lição 12
logger.addHandler(handler)


def log_action(action, iteration: int, step: str = ""):
    """Regista uma ação de um 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 o texto em si: apenas o seu comprimento
            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())

Nível 2: Decisões do modelo

Registe o que o modelo diz sobre as suas escolhas para compreender por que razão selecionou uma ação específica. Um clique em coordenadas inesperadas não significa nada por si só; associado à frase que o precedeu — «o botão de submissão parece estar oculto pelo banner de cookies» — torna-se um diagnóstico. O texto é truncado para duzentos caracteres, mais do que suficiente para compreender a intenção sem explodir o volume do ficheiro. Existem duas fontes de texto numa resposta da API Responses. As mensagens intermédias que o modelo escreve antes de agir têm phase: "commentary", enquanto a resposta final tem phase: "final_answer". E se o modelo em uso suportar resumos de raciocínio, obtém-nos solicitando-os (reasoning={"summary": "auto"}): chegam em elementos do tipo reasoning.

O consumo de tokens é registado ao mesmo ritmo e merece atenção redobrada: mesmo com previous_response_id, todos os tokens de entrada de respostas anteriores na cadeia são novamente faturados como entrada, incluindo as capturas de ecrã. O custo de um turno aumenta, portanto, à medida que a sessão se prolonga.

def log_model_response(response, iteration: int):
    """Regista notas, resumos e chamadas de uma resposta (excluindo imagens)."""
    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,
    )

Nível 3: Capturas de ecrã

Guarde as capturas de ecrã para depuração post-mortem, mas vigie o espaço em disco: uma captura PNG pesa frequentemente várias centenas de quilobytes e um fluxo de trabalho longo produz centenas delas. A classe abaixo resolve isto com uma rotação simples. O nome do ficheiro começa com um carimbo de data/hora, alinhando a ordem alfabética com a ordem cronológica; a ordenação em _cleanup é então suficiente para identificar as capturas mais antigas e eliminá-las até voltar a ficar abaixo do limite de cem ficheiros. O campo label permite anotar momentos interessantes, por exemplo error ou before_validation, e identificá-los à primeira vista na pasta.

from datetime import datetime, timezone
from pathlib import Path

class ScreenshotLogger:
    """Guarda capturas de ecrã com rotação."""

    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 uma captura de ecrã com um nome descritivo."""
        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 de ecrã antigas."""
        files = sorted(self.base_dir.glob("*.png"))
        while len(files) > self.max_files:
            files[0].unlink()
            files.pop(0)

Métricas a monitorizar

Taxa de
sucesso por fluxo
Duração
média por passo
Custo
em tokens por execução
Erros
por tipo e frequência

Estes quatro indicadores só têm valor quando comparados consigo mesmos ao longo do tempo: um fluxo de trabalho que desce de noventa e cinco para oitenta por cento de sucesso indica que uma interface se moveu, muito antes da primeira queixa do utilizador. Implemente, portanto, um coletor de métricas associado a cada execução. A classe de dados WorkflowMetrics acumula tokens iteração após iteração, mantém o registo de erros com o seu passo e carimbo de data/hora, e expõe duas propriedades calculadas: a duração, que funciona mesmo que o fluxo de trabalho ainda não tenha terminado, e uma estimativa de custo baseada no preço do modelo em uso, que deve obter da página de preços da OpenAI em vez de a codificar fixamente. O método summary produz o dicionário compacto que irá arquivar em cada execução.

from dataclasses import dataclass, field
from datetime import datetime, timezone

def now() -> datetime:
    return datetime.now(timezone.utc)

@dataclass
class WorkflowMetrics:
    """Recolhe métricas para um fluxo de trabalho."""
    workflow_id: str
    input_price_per_million: float  # preço para o modelo em 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:
        # Estimativa: cache de prompts e ambiente alojado não são contados
        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}",
        }

Painel de monitorização

Para monitorização em tempo real, envie as métricas para um serviço de monitorização em vez de as deixar adormecer num ficheiro. A função abaixo publica o resumo com carimbo de data/hora num endpoint HTTP, com duas precauções tão importantes quanto o próprio envio: um atraso máximo de cinco segundos e uma excecão capturada que se limita a um aviso. Um coletor de métricas indisponível nunca deve derrubar o fluxo de trabalho que observa — o oposto seria a definição de uma supervisão contraproducente.

import requests  # pip install requests

def push_metrics(metrics: WorkflowMetrics, endpoint: str):
    """Envia métricas para um serviço de monitorização."""
    payload = metrics.summary()
    payload["timestamp"] = now().isoformat()

    try:
        requests.post(
            endpoint,
            json=payload,  # o requests define o cabeçalho JSON por si
            timeout=5,
        )
    except requests.RequestException as e:
        logger.warning(f"Metrics push error: {e}")

Alertas automáticos

Um painel que ninguém observa é apenas um arquivo. Configure, portanto, alertas baseados em limiares para que a anomalia venha ter consigo. As quatro condições aqui retidas cobrem desvios clássicos: um custo superior a dois dólares, uma duração excedendo três minutos, mais de trinta iterações ou mais de dois erros na mesma execução. Estes valores são pontos de partida, não verdades: calibre-os com base em medições das suas próprias execuções bem-sucedidas, colocando o limiar bem acima da sua mediana observada. Um alerta que dispare todos os dias será ignorado na segunda semana.

def check_alerts(metrics: WorkflowMetrics):
    """Verifica limiares e aciona 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 notificação (email, Slack, etc.)

    return alerts

Crie o hábito de chamar check_alerts imediatamente após finalize e depois push_metrics: obtém um rasto arquivado em cada execução, um sinal enviado para o painel e uma notificação apenas quando algo merece a sua atenção.

Pontos-chave

  • Registe ações, mensagens e resumos do modelo, e capturas em três níveis separados
  • Monitore a taxa de sucesso, duração, custo em tokens e erros; o histórico encadeado é faturado como entrada em cada turno
  • Implemente rotação de capturas de ecrã para evitar saturar o disco
  • Configure alertas automáticos em limiares críticos
  • Nunca registe dados sensíveis (palavras-passe, tokens, dados pessoais)