Observabilidade também é contexto para agentes
Este é o terceiro artigo da série sobre arquitetura AI friendly. Já falamos sobre como uma IA se parece com uma pessoa nova entrando na empresa e sobre a importância de conectar código, documentação e decisões arquiteturais.
Agora quero falar sobre uma fonte de contexto que muitas vezes é tratada apenas como ferramenta operacional: a observabilidade.
O sistema real não está apenas no repositório
Quando analisamos um sistema pelo código, vemos uma fotografia daquilo que foi implementado.
Mas o sistema que está rodando em produção pode contar uma história diferente.
Uma configuração pode ter sido alterada. Uma dependência pode estar mais lenta. Um determinado fluxo pode ser muito mais utilizado do que a equipe imaginava. Uma regra pode funcionar corretamente na maioria dos casos, mas falhar em uma combinação específica de dados.
O código mostra o que deveria acontecer. A observabilidade ajuda a entender o que está acontecendo de verdade.
Essa diferença é importante para pessoas e para agentes de IA.
Observabilidade não é só monitoramento
Monitoramento costuma responder a uma pergunta simples: existe algo errado?
Observabilidade tenta responder a uma pergunta mais completa: por que o sistema está se comportando dessa forma?
Para isso, usamos diferentes sinais:
logs mostram eventos e detalhes de uma execução;
métricas mostram tendências, volumes e variações;
traces mostram o caminho de uma requisição entre diferentes serviços;
eventos de deploy mostram quando uma mudança entrou em produção;
dados de negócio mostram o impacto para quem usa o sistema.
Cada sinal explica uma parte do comportamento. Quando eles estão conectados, fica mais fácil construir uma hipótese e verificar se ela faz sentido.
Onde cada parte vive
Assim como a documentação não precisa estar dentro do código, os dados de observabilidade também não precisam ficar armazenados no repositório.
O serviço gera eventos e sinais. Uma camada de instrumentação coleta esses sinais. A plataforma de observabilidade armazena e correlaciona os dados. A documentação explica o significado das métricas, dos alertas e dos fluxos importantes.
O repositório pode manter apenas a configuração da instrumentação, os nomes dos sinais e links para os dashboards e runbooks. O histórico dos dados continua na plataforma operacional, que é o lugar adequado para consultar o comportamento do sistema ao longo do tempo.
O importante é conectar essas fontes. Um agente precisa conseguir sair do serviço no repositório, chegar ao dashboard correto e encontrar a explicação do que está vendo.
Um incidente é uma investigação de contexto
Imagine que a latência de uma API começou a aumentar.
Uma pessoa experiente talvez saiba exatamente onde olhar. Ela conhece o dashboard certo, lembra de um incidente parecido e sabe qual serviço costuma causar aquele tipo de problema.
Uma pessoa nova não tem esse conhecimento. Um agente também não.
Para investigar, eles precisam encontrar uma sequência de evidências:
Quando o problema começou?
Qual serviço apresentou o primeiro sinal?
O aumento aconteceu para todos os usuários ou apenas para um fluxo?
Houve algum deploy ou mudança de configuração nesse período?
Qual dependência começou a responder mais devagar?
O aumento de latência afetou alguma métrica de negócio?
Essas perguntas não são respondidas por um único dashboard. Elas exigem que diferentes fontes sejam relacionadas.
É por isso que observabilidade também é contexto. Ela fornece evidências sobre o comportamento do sistema em uma situação específica.
Logs precisam contar uma história
Um log com uma mensagem solta pode até ajudar alguém que conhece o código. Para uma investigação mais ampla, ele costuma ser insuficiente.
Compare estes dois exemplos:
Erro ao processar pagamento
{
"event": "payment_processing_failed",
"order_id": "ord_123",
"payment_provider": "provider_a",
"error_code": "timeout",
"retry_count": 2,
"request_id": "req_456",
"occurred_at": "2026-08-20T18:30:00Z"
}
O segundo exemplo não é melhor apenas porque está em JSON. Ele é melhor porque carrega informações que permitem relacionar o evento com outros sinais.
Com um request_id, podemos seguir a requisição em diferentes serviços. Com um order_id, podemos entender o impacto em uma transação específica. Com o código de erro, podemos agrupar falhas parecidas. Com o horário, podemos comparar o evento com deploys e alterações de infraestrutura.
Logs estruturados são uma forma de tornar o comportamento do sistema mais legível.
Métricas precisam ter significado
Também é possível ter muitos dashboards e ainda assim ter pouca observabilidade.
Uma métrica só é útil quando sabemos o que ela representa, qual comportamento esperado ela descreve e em que situação devemos prestar atenção nela.
Por exemplo, uma métrica chamada request_count pode indicar o número de requisições. Mas precisamos saber:
qual é a unidade de tempo;
qual serviço produz essa métrica;
quais filtros estão disponíveis;
qual variação é considerada normal;
como ela se relaciona com erros e latência.
Sem esse contexto, o agente pode encontrar a métrica correta e ainda assim interpretá-la de forma errada.
Uma boa prática é documentar as métricas mais importantes junto com seus significados, dimensões e limites conhecidos. O dashboard deixa de ser apenas uma coleção de gráficos e passa a ser uma explicação visual do sistema.
Traces conectam a arquitetura ao comportamento
Em uma arquitetura distribuída, uma requisição pode atravessar vários serviços antes de chegar ao usuário.
Quando observamos apenas cada serviço de forma isolada, perdemos parte da história. Um trace permite acompanhar o caminho completo e descobrir onde o tempo foi gasto.
Isso ajuda a responder perguntas como:
qual serviço adicionou mais latência;
qual chamada foi repetida várias vezes;
onde ocorreu o primeiro erro;
qual dependência externa está afetando o fluxo;
se uma falha em um serviço está causando efeitos em outros.
Para um agente, traces são especialmente úteis porque conectam o mapa arquitetural com uma execução real. Eles mostram como os componentes se comportaram juntos, e não apenas como foram descritos em um documento.
Contexto operacional precisa incluir negócio
Um dos erros mais comuns em observabilidade é olhar apenas para a saúde técnica do sistema.
CPU, memória, taxa de erro e latência são importantes. Mas nem sempre mostram o impacto real para as pessoas que usam o produto.
Uma API pode estar respondendo com sucesso, enquanto uma etapa importante do negócio está falhando. Um fluxo pode ter poucos erros, mas afetar justamente os clientes mais importantes. Uma fila pode estar processando mensagens, mas com um atraso que torna a experiência do usuário ruim.
Por isso, vale conectar sinais técnicos com eventos de negócio:
pagamentos aprovados;
pedidos finalizados;
documentos processados;
usuários que concluíram uma etapa;
transações que precisaram de intervenção manual.
Esse tipo de contexto ajuda o agente a priorizar o que realmente importa. Nem todo alerta técnico representa um incidente para o negócio, e nem todo problema de negócio aparece como um erro técnico óbvio.
O que acontece depois de um deploy?
Uma mudança de código só pode ser avaliada de verdade depois que começa a rodar.
Por isso, o contexto de uma alteração deveria incluir também a relação com os sinais de produção. Quando um deploy acontece, deveria ser possível responder:
quais serviços foram alterados;
quais métricas precisam ser acompanhadas;
quais comportamentos seriam esperados;
quais alertas podem indicar uma regressão;
como comparar o comportamento anterior e o atual.
Com essas relações, um agente pode ajudar não apenas a escrever uma mudança, mas também a verificar se ela produziu o resultado esperado.
Como preparar a observabilidade para agentes
Não é necessário começar instrumentando tudo. É melhor escolher um fluxo importante e torná-lo compreensível de ponta a ponta.
Alguns passos ajudam:
Escolha um fluxo relevante para o negócio.
Garanta que ele tenha um identificador de correlação.
Estruture os logs principais desse fluxo.
Crie métricas com nomes e significados claros.
Verifique se os traces atravessam os serviços envolvidos.
Relacione deploys, incidentes e mudanças de configuração.
Documente o que é normal e o que indica comportamento anormal.
O resultado esperado não é apenas um conjunto de dashboards mais bonitos. É um sistema que consegue contar a própria história quando algo muda.
Conclusão
Observabilidade é uma das formas mais importantes de dar contexto para agentes de IA.
Código e documentação explicam como o sistema foi pensado. Logs, métricas e traces mostram como ele se comporta quando está sendo usado de verdade.
Quando esses sinais são estruturados, correlacionados e ligados ao contexto de negócio, uma pessoa nova ou um agente consegue investigar problemas com menos dependência de quem já conhece o sistema.
No próximo artigo, vou falar sobre skills. A ideia é entender como oferecer ao agente o contexto certo para cada problema, com especializações para observabilidade, delivery, dados e outros domínios técnicos.