Como Usar LangSmith para Monitorar e Depurar Agentes de IA em Produção

Colocar agentes de IA em produção é um divisor de águas para qualquer produto, mas também abre porta para desafios técnicos complexos. Diferente de softwares tradicionais onde o fluxo de execução é totalmente determinístico, sistemas baseados em LLMs executam chamadas encadeadas, tomam decisões autônomas e podem entrar em loops infinitos de ferramentas ou alucinar sem emitir nenhuma exceção nos logs padrão.

É nesse cenário que a observabilidade de LLMs deixa de ser um luxo e passa a ser um requisito básico de arquitetura. Neste artigo, você verá como usar o LangSmith para eliminar a opacidade dos seus agentes de IA, rastreando a árvore de execução completa, analisando o consumo de tokens e corrigindo falhas antes que afetem seus usuários.

O Que É o LangSmith e Por Que Ele É Essencial para Agentes

O LangSmith é uma plataforma de LLMOps e observabilidade desenvolvida pela criadora do LangChain para monitorar, testar e avaliar aplicações baseadas em modelos de linguagem. Ele funciona capturando automaticamente os dados de cada requisição enviada ao modelo, desde os prompts de sistema até a execução de function calling e ferramentas.

Em arquiteturas com agentes autônomos ou fluxos ReAct (Reasoning and Acting), uma simples mensagem do usuário pode desencadear dezenas de etapas intermediárias. Sem uma ferramenta dedicada, entender o motivo de uma resposta incorreta exige analisar extensos arquivos de log brutos, o que torna o debugging de produção extremamente lento.

Com o LangSmith, cada execução é organizada em uma estrutura hierárquica conhecida como trace de execução. Isso permite visualizar visualmente o caminho percorrido pelo agente, inspecionar as entradas e saídas de cada ferramenta e mensurar a latência individual de cada nó da aplicação.

4 Passos para Instrumentar e Monitorar Agentes com LangSmith

Siga esta metodologia prática para integrar a observabilidade do LangSmith na sua aplicação e começar a inspecionar execuções complexas em minutos.

1. Configure as variáveis de ambiente no seu projeto

Adicione suas credenciais do LangSmith (`LANGCHAIN_API_KEY`) e habilite o rastreamento global definindo `LANGCHAIN_TRACING_V2=true`. Isso garante a coleta automática de traces sem precisar alterar a estrutura principal do seu código.

2. Instrumente funções customizadas com o decorador @traceable

Para rastrear rotinas próprias que não usam LangChain, utilize o decorador `@traceable` da biblioteca `langsmith`. Ele registra entradas e saídas de funções diretamente na árvore de execução no painel.

3. Defina metadados e tags para segmentação

Envie identificadores de contexto como `user_id`, `environment` e `session_id` nas requisições. Essa prática facilita o filtro de sessões específicas e acelera o diagnóstico de erros por ambiente ou versão de deploy.

4. Analise a árvore de chamadas e identifique gargalos

Acesse a interface visual do LangSmith para inspecionar nós individuais. Avalie a latência por etapa, os parâmetros enviados a cada API externa e a contagem exata de tokens gastos em cada iteração do agente.

Exemplo Prático: Depurando um Agente de Suporte que Entrou em Loop

Considere o cenário em que um agente de atendimento ao cliente trava e estoura o tempo limite ao tentar buscar informações sobre uma fatura.

• Identificação do sintoma:: No painel de monitoramento do LangSmith, a requisição do usuário aparece com tempo de resposta superior a 20 segundos e consumo anormal de tokens de entrada.
• Inspeção da árvore de chamadas:: Ao abrir o trace completo, observa-se que o LLM chamou a ferramenta `consultar_fatura` cinco vezes consecutivas, recebendo um retorno nulo a cada tentativa.
• Diagnóstico da causa raiz:: Analisando o prompt de sistema capturado no trace, nota-se que não havia uma instrução clara de como o agente deveria agir quando a API retornasse dados vazios.
• Correção e reteste:: Após atualizar o prompt com uma regra de fallback e re-executar a mesma entrada no Playground do LangSmith, o agente respondeu adequadamente solicitando o CPF do cliente.

Ao identificar o ponto exato da falha na árvore de execução, a correção levou minutos em vez de horas de testes manuais.

3 Erros Comuns ao Monitorar Agentes em Produção

• Vazamento de dados sensíveis (PII):. Enviar informações pessoais de usuários aos logs do LangSmith sem aplicar um filtro ou mascaramento prévio, violando diretrizes da LGPD.
• Ignorar alertas de estouro de tokens:. Não configurar limites de custo no painel, permitindo que agentes com defeito entrem em loops infinitos e consumam o orçamento de APIs de LLM.
• Monitorar apenas o modelo e esquecer as ferramentas:. Focar toda a análise nas respostas geradas pelo LLM e deixar de instrumentar o tempo de resposta das APIs de ferramentas externas integradas ao agente.

Próximos Passos para Elevar a Observabilidade dos Seus Agentes

Adotar o LangSmith é o passo decisivo para transformar um protótipo experimental em um sistema resiliente em produção. Comece ativando o rastreamento em ambiente de desenvolvimento, analise os traces com maior latência e crie conjuntos de dados de avaliação baseados nas falhas reais identificadas durante a operação.