Monitorização e registo de eventos
Nesta página
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_calle os elementos deresponse.output(mensagens com a suaphase, resumos de raciocínio, chamadas), em vez dos blocostool_useda API da Anthropic; o preço fixo do Claude Sonnet foi substituído pelo preço do modelo em uso, e o método obsoletodatetime.utcnow()(desde o Python 3.12) foi substituído pordatetime.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
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)