# Observabilidade também é contexto para agentes de IA - Author: Luiz Schons - Published: 2026-08-21 - URL: https://luizschons.com/pt-br/posts/observability-is-also-context-for-ai-agents/ - English: https://luizschons.com/posts/observability-is-also-context-for-ai-agents.md - Temas: IA, Observabilidade Este é o terceiro artigo de uma série sobre arquitetura amigável à IA. Já falamos sobre como a IA se parece com uma nova pessoa entrando em uma 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 costuma ser tratada apenas como uma ferramenta de operações: observabilidade. ## O sistema real não está apenas no repositório Quando olhamos para um sistema por meio do seu código, vemos uma imagem do que foi construído. Mas o sistema em produção pode contar uma história diferente. Uma configuração pode ter mudado. Uma dependência pode estar mais lenta. Um determinado fluxo pode ser usado muito mais do que a equipe esperava. Uma regra pode funcionar corretamente na maioria dos casos, mas falhar com uma combinação específica de dados. O código mostra o que deveria acontecer. A observabilidade nos ajuda a entender o que realmente está acontecendo. Essa diferença importa tanto para as pessoas quanto para os agentes de IA. ## Observabilidade não é apenas monitoramento O monitoramento normalmente responde a uma pergunta simples: há algo errado? A observabilidade tenta responder a uma pergunta maior: por que o sistema está se comportando dessa forma? Para isso, usamos sinais diferentes: - registros mostram eventos e detalhes de uma execução; - métricas mostram tendências, volumes e mudanças; - rastreamentos mostram o caminho de uma requisição por diferentes serviços; - eventos de implantação mostram quando uma mudança foi para produção; - dados de negócio mostram o impacto nas pessoas que usam o sistema. Cada sinal explica uma parte do comportamento do sistema. Quando esses sinais estão conectados, fica mais fácil criar uma possível explicação e verificar se ela faz sentido. ## Onde cada parte fica Assim como a documentação não precisa estar dentro do código, os dados de observabilidade não precisam ser armazenados no repositório. O serviço cria eventos e sinais. Uma camada de instrumentação coleta esses sinais. A plataforma de observabilidade armazena e conecta os dados. A documentação explica o significado de métricas, alertas e fluxos importantes. Observabilidade como contexto O repositório pode manter apenas as configurações de instrumentação, os nomes dos sinais e links para dashboards e runbooks. O histórico dos dados permanece na plataforma de operações, que é o lugar certo para verificar como o sistema se comporta 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 uma explicação do que está observando. ## Um incidente é uma investigação de contexto Imagine que a latência de uma API começa 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 normalmente causa esse tipo de problema. Uma pessoa nova não tem esse conhecimento. Um agente também não. Para investigar o problema, é preciso encontrar uma sequência de pistas: - Quando o problema começou? - Qual serviço apresentou o primeiro sinal? - O aumento afetou todos os usuários ou apenas um fluxo? - Houve uma implantação ou uma mudança de configuração nesse período? - Qual dependência começou a responder mais lentamente? - O aumento da latência afetou alguma métrica de negócio? Um único dashboard não consegue responder a todas essas perguntas. Elas exigem informações de fontes diferentes. É por isso que observabilidade também é contexto. Ela fornece evidências sobre como o sistema se comporta em uma situação específica. ## Os registros precisam contar uma história Um log com uma mensagem curta pode ajudar alguém que conhece o código. Para uma investigação maior, normalmente não é suficiente. Compare estes dois exemplos: ```text Error processing payment ``` ```json { "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 é melhor porque contém informações que podem ser conectadas a outros sinais. Com um `request_id`, podemos acompanhar a requisição por diferentes serviços. Com um `order_id`, podemos entender o impacto em uma transação. Com o código de erro, podemos agrupar falhas semelhantes. Com o timestamp, podemos comparar o evento com deploys e mudanças de infraestrutura. Registros estruturados tornam o comportamento do sistema mais fácil de entender. ## As métricas precisam ter significado É possível ter muitos dashboards e ainda assim ter uma observabilidade ruim. Uma métrica só é útil quando sabemos o que ela significa, qual comportamento descreve e quando devemos prestar atenção nela. Por exemplo, uma métrica chamada `request_count` pode mostrar o número de requisições. Mas também precisamos saber: - qual é a unidade de tempo; - qual serviço cria essa métrica; - quais filtros estão disponíveis; - qual mudança é considerada normal; - como ela se relaciona com erros e latência. Sem esse contexto, um agente pode encontrar a métrica certa e ainda assim entendê-la de forma incorreta. Uma boa prática é documentar as métricas mais importantes com seu significado, dimensões e limitações conhecidas. O dashboard se torna uma explicação visual do sistema. ## Rastreamentos conectam arquitetura e comportamento Em uma arquitetura distribuída, uma requisição pode passar por vários serviços antes de chegar ao usuário. Quando olhamos para cada serviço separadamente, perdemos parte da história. Um trace permite acompanhar o caminho completo e ver 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 problemas em outros. Para um agente, rastreamentos conectam o mapa da arquitetura a uma execução real. Eles mostram como os componentes trabalharam juntos, não apenas como foram descritos em um documento. ## O contexto operacional precisa incluir o negócio Um erro comum em observabilidade é olhar apenas para a saúde técnica do sistema. CPU, memória, taxa de erros e latência são importantes. Mas nem sempre mostram o impacto real nas pessoas que usam o produto. Uma API pode retornar uma resposta bem-sucedida enquanto uma etapa importante do negócio falha. Um fluxo pode ter poucos erros, mas afetar os clientes mais importantes. Uma fila pode processar mensagens, mas com um atraso que cria uma experiência ruim para o usuário. Por isso, é útil conectar sinais técnicos a eventos de negócio: - pagamentos aprovados; - pedidos concluídos; - documentos processados; - usuários que concluíram uma etapa; - transações que precisaram de ajuda manual. Esse contexto ajuda o agente a se concentrar no que realmente importa. Nem todo alerta técnico é um incidente de negócio, e nem todo problema de negócio aparece como um erro técnico óbvio. ## O que acontece depois de uma implantação? Uma mudança de código só pode ser avaliada corretamente depois que começa a executar. O contexto de uma mudança também deve incluir sua conexão com os sinais de produção. Quando uma implantação acontece, devemos conseguir responder: - quais serviços mudaram; - quais métricas precisam ser observadas; - qual comportamento esperamos; - quais alertas podem indicar um problema; - como comparar o comportamento antigo com o novo. Com essas conexõ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 Você não precisa instrumentar tudo de uma vez. É melhor escolher um fluxo importante e torná-lo fácil de entender do início ao fim. Estas etapas podem ajudar: - Escolha um fluxo que seja importante para o negócio. - Garanta que ele tenha um ID de correlação. - Estruture os principais registros desse fluxo. - Crie métricas com nomes e significados claros. - Verifique se os rastreamentos passam pelos serviços envolvidos. - Conecte deploys, incidentes e mudanças de configuração. - Documente o que é normal e o que indica um comportamento incomum. O objetivo não é apenas criar dashboards mais bonitos. O objetivo é construir um sistema capaz de contar sua própria história quando algo muda. ## Conclusão Observabilidade é uma das formas mais importantes de fornecer contexto a agentes de IA. Código e documentação explicam como o sistema foi projetado. Registros, métricas e rastreamentos mostram como ele se comporta quando as pessoas realmente o estão usando. Quando esses sinais estão estruturados, conectados e relacionados ao contexto de negócio, uma pessoa nova ou um agente de IA pode investigar problemas com menos ajuda de quem já conhece o sistema. No próximo artigo, falarei sobre habilidades. A ideia é entender como fornecer a um agente o contexto certo para cada problema, com habilidades especializadas para observabilidade, entrega, dados e outras áreas técnicas.