O chat não é observabilidade: registre os eventos do seu agente

Um agente recebe uma tarefa simples: gerar uma imagem, ajustar o arquivo e preparar um post. Depois de alguns minutos, a tela mostra apenas "não foi possível concluir".

Só que o arquivo está na pasta de saída.

A geração falhou ou a resposta da ferramenta se perdeu? O agente parou esperando uma aprovação? O login expirou? O timeout aconteceu antes ou depois de gravar o arquivo? Se a única fonte disponível for o histórico da conversa, responder a essas perguntas vira arqueologia.

O chat continua sendo uma boa interface para pedir trabalho e acompanhar o resultado. Para depurar a execução, porém, você precisa de outra coisa: eventos correlacionados que mostrem o que o executor tentou, onde esperou, qual efeito ocorreu e por que parou.

Não precisa começar com uma plataforma enorme de observabilidade. Um registro pequeno e bem definido já resolve boa parte do mistério.

O chat achata uma execução que aconteceu em etapas

Uma resposta final condensa ações diferentes em um parágrafo. Ela pode esconder que o agente:

chamou uma ferramenta duas vezes;
criou um arquivo antes de receber um timeout;
aguardou aprovação humana por quatro minutos;
retomou depois de uma autenticação;
recebeu uma saída parcial e tentou novamente.

Esses detalhes mudam o diagnóstico. Se um arquivo foi criado, repetir a chamada pode duplicar uma publicação ou sobrescrever um artefato válido. Se o tempo foi gasto esperando uma pessoa, aumentar o limite do modelo não ataca a causa. Se houve uma saída parcial, apagar a tentativa anterior elimina justamente a pista mais útil.

A mensagem no chat é uma projeção para leitura humana. A ordem das chamadas e dos efeitos precisa vir de um registro próprio.

Comece com um envelope de evento pequeno

Eu começaria com poucos campos, escolhidos para responder perguntas operacionais:

event_id identifica o evento;
run_id agrupa uma execução;
call_id liga a solicitação de uma ferramenta ao resultado correspondente;
type, status e horário dizem o que aconteceu e quando;
ferramenta ou ator, duração, referência de artefato e classe de erro entram quando fizerem sentido.

Os nomes são uma proposta didática para um sistema próprio, não o formato de uma API específica. O importante é manter identificadores estáveis e uma relação explícita entre causa e efeito.

Três linhas de JSONL já conseguem expor uma situação que o chat resumiria apenas como falha:

{"event_id":"evt-041","run_id":"run-202","call_id":"call-007","type":"tool.requested","status":"pending","tool":"prepare_image","at":"2026-09-22T02:14:01Z"}
{"event_id":"evt-042","run_id":"run-202","call_id":"call-007","type":"artifact.created","status":"succeeded","artifact_ref":"sha256:8f2...","width":1080,"height":1350,"at":"2026-09-22T02:14:03Z"}
{"event_id":"evt-043","run_id":"run-202","call_id":"call-007","type":"tool.failed","status":"failed","error_class":"response_timeout","effect":"partial","at":"2026-09-22T02:14:31Z"}

Esse exemplo é ilustrativo. Ele mostra que a ferramenta foi solicitada, um artefato apareceu e a comunicação terminou em timeout. Agora o próximo passo pode verificar o arquivo antes de decidir por um novo retry.

Sem o call_id, você tem três linhas soltas. Sem a referência do artefato, sabe que algo foi criado, mas não sabe o quê. Sem preservar a falha, a timeline parece ter terminado com sucesso.

Modele o ciclo da ferramenta, não apenas o resultado final

Registrar somente tool.succeeded e tool.failed deixa buracos. Uma chamada tem pelo menos uma solicitação, um período de execução e um desfecho. Em fluxos com efeitos externos, também pode haver artefatos e checkpoints no meio.

Um vocabulário inicial poderia incluir:

run.started e run.finished;
tool.requested, tool.succeeded e tool.failed;
approval.requested e approval.decided;
artifact.created;
validation.finished.

Não transforme essa lista em uma taxonomia infinita. Adicione um tipo quando ele ajuda a tomar uma decisão concreta. Se duas equipes interpretam tool.failed de maneiras incompatíveis, vale separar as situações. Se ninguém consulta uma distinção, talvez ela ainda não mereça outro evento.

Um retry deve criar uma nova tentativa, sem reescrever a anterior. Guarde o mesmo run_id, use outro call_id ou um campo attempt e preserve o erro original. Assim fica visível se a segunda tentativa corrigiu uma falha transitória ou apenas repetiu um efeito já aplicado.

Também evite assumir que timeout significa "nada aconteceu". Quando o executor perde a resposta, o efeito pode ser desconhecido. Esse estado pede verificação antes de repetição automática.

Aprovação e autenticação precisam aparecer na timeline

Uma pausa humana não é latência do modelo. Uma autenticação pendente também não é falha técnica. Se tudo vira um intervalo silencioso, o painel acaba culpando a parte errada do sistema.

Para uma aprovação, registre o pedido, o escopo apresentado, a decisão, o papel autorizado e a retomada da execução. Não é necessário salvar credenciais nem copiar dados pessoais para o log. Um identificador interno ou papel pode ser suficiente, conforme as regras do produto.

A decisão precisa carregar contexto. "Aprovado" sozinho é fraco. A pessoa aprovou qual arquivo, para qual destino e com qual ação? Uma aprovação negada também deve encerrar ou redirecionar a execução de forma explícita, em vez de aparecer como erro genérico.

Na autenticação, registre que o fluxo foi solicitado, concluído, cancelado ou expirou. Tokens, cookies e segredos ficam fora do evento. Observabilidade não pode virar uma coleção paralela de credenciais.

Use um workflow visual como teste de realidade

Fluxos com imagem deixam os efeitos intermediários fáceis de enxergar. Considere esta sequência:

O agente gera uma imagem.
Uma etapa valida formato, dimensões e integridade do arquivo.
Alguém prepara o tamanho final para a rede social.
A pessoa responsável confere o resultado e aprova a publicação.
A ferramenta publica o post.

Na terceira etapa, uma opção prática é abrir o Resize Image for Instagram para ajustar o arquivo localmente no navegador antes da aprovação. O redimensionamento acontece no próprio navegador, sem enviar os pixels da imagem para processamento no servidor.

O log não precisa carregar a imagem inteira. Pode guardar uma referência, um hash, as dimensões de entrada e saída e o resultado do checkpoint. A aprovação aponta para esse mesmo artefato. Se a publicação falhar depois, você ainda consegue provar qual versão havia sido aprovada.

Esse exemplo também expõe um limite importante: artifact.created não significa artifact.validated. O arquivo pode existir e ter dimensões erradas, estar corrompido ou não corresponder ao pedido. Geração e validação merecem eventos separados.

Faça a timeline nascer dos eventos

Atualizações recentes do Agent Inspector caminham nessa direção: permitem buscar eventos por tipo ou conteúdo JSON, filtrar categorias, exportar recortes em JSONL, correlacionar resultados com suas chamadas e preservar saída parcial ou detalhes de erro quando um stream é interrompido.

A lição útil não é copiar o formato interno de um fornecedor. É tratar timeline, busca e resumo como visões derivadas de uma base correlacionada. Se a interface for a única fonte de verdade, qualquer mudança de tela pode apagar informação operacional.

Comece pelas consultas que você realmente fará:

mostrar todas as chamadas de uma execução;
encontrar aprovações ainda pendentes;
localizar falhas por ferramenta e classe de erro;
listar artefatos criados antes de um timeout;
separar tempo de execução de tempo de espera.

JSONL é conveniente para anexar eventos e enviar um recorte a um caso de suporte. Ele não garante ordem global, correlação correta nem busca eficiente. Essas propriedades vêm dos identificadores, das regras de escrita e do armazenamento escolhido.

Antes de ligar o registro em produção, defina mascaramento, retenção e limites de tamanho. Prefira referências a payloads completos. Prompts integrais, raciocínio privado, imagens, dados pessoais e segredos raramente precisam estar no evento. Mais detalhe pode acelerar um diagnóstico e, ao mesmo tempo, ampliar custo, ruído e risco.

Validação deve produzir evidência própria

Uma execução terminar não comprova que o resultado está certo. O padrão usado em sistemas de segurança do Google ajuda a enxergar a separação: uma etapa rápida aponta um possível problema, outra valida a estrutura com AST, grafo de chamadas e regras de domínio, e a correção ainda segue para revisão humana.

Um time pequeno não precisa copiar essa escala. A ideia transferível é separar geração de verificação. Se o agente produz uma alteração, o teste, o lint, a inspeção do artefato ou a regra de negócio devem emitir resultados próprios.

Por isso, validation.finished deveria informar qual artefato foi verificado, qual regra rodou e qual foi o resultado. Acrescentar "parece correto" à resposta do chat não cria evidência independente.

Um schema portátil facilita comparar executores, mas pode perder detalhes úteis de cada um. Vale manter um núcleo comum e reservar metadados específicos para cada integração, sem deixar o restante do sistema dependente deles.

Teste a observabilidade provocando falhas

Não espere o primeiro incidente para descobrir que seus eventos são insuficientes. Monte um fluxo pequeno e provoque situações incômodas de propósito:

faça uma ferramenta criar o arquivo e perder a resposta em seguida;
negue uma aprovação;
interrompa a autenticação;
force um timeout e depois uma nova tentativa;
envie uma saída grande o bastante para exigir truncamento seguro.

Depois feche o chat e tente responder: qual chamada falhou? Houve efeito parcial? Quanto tempo foi gasto esperando? Qual artefato pode ser retomado? Quem decidiu interromper? Se o registro não responde, ajuste o schema antes de adicionar outro painel.

Eventos imutáveis ajudam a reconstruir a sequência, mas não anulam políticas de exclusão de dados sensíveis. Auditoria e privacidade precisam ser desenhadas juntas. O mesmo vale para custo: guardar tudo indefinidamente costuma ser uma maneira cara de adiar decisões sobre o que é útil.

O primeiro passo cabe no próximo agente

Escolha uma execução curta, defina meia dúzia de tipos de evento e grave cada linha com run_id e call_id. Adicione referências de artefato, aplique mascaramento na origem e crie uma visualização simples por ordem de tempo. Em seguida, quebre o fluxo de três ou quatro maneiras.

O teste de sucesso não é ter um dashboard bonito. É conseguir explicar uma falha sem reler a conversa inteira e sem adivinhar se a ferramenta produziu um efeito.

Mantenha o chat para conversar com o agente. Para operar o agente, guarde os eventos.