Observabilidade com LangSmith

O LangSmith é a ferramenta de observabilidade do LangChain. Com o monitoramento ligado, cada resposta do agente vira um registro (um trace) com o passo a passo: o que o modelo recebeu, o que pensou responder, quais tools chamou com quais argumentos, o que cada tool devolveu, quanto tempo e quantos tokens cada passo gastou, e onde falhou. É o instrumento de trabalho de quem cuida do agente. O chat do painel mostra o que o lead leu; o LangSmith mostra por que o agente respondeu aquilo. A conta e a chave são da agência. A Zatten só envia os dados para a conta indicada no agente.

​

O que dá para fazer

​

Criar a conta e a chave

​

Ligar no agente

Menu Agente (/project) → ícone de configurações ao lado do Modelo → Monitoramento. Salve e publique (Versões e publicação). Conversas em andamento começam a enviar em até 2 minutos. Um projeto do LangSmith por projeto da Zatten. Use um nome que identifique o cliente final, como zatten-clinica-sorriso. Misturar clientes num projeto só mistura custos e dados pessoais de clientes diferentes. Tags e metadados (só pelo template): tags marca todos os traces do agente (ex.: ["producao", "clinica-sorriso"]); metadata acrescenta pares chave-valor fixos. Os dois servem para filtrar.

​

O que vai para o LangSmith

Cada resposta do agente é um trace. Dentro dele:

• A entrada: as mensagens novas do lead (o lote juntado pelo buffer).
• Cada chamada ao modelo: as mensagens enviadas (prompt, histórico, o bloco “Contexto do lead atual” e o bloco “Agora” do contexto injetado), a resposta, o modelo usado, os tokens de entrada e saída e o tempo.
• Cada chamada de tool: o nome, os argumentos que o modelo preencheu e o texto exato que voltou para o modelo.
• Os passos internos: resumo do histórico, transcrição de áudio, troca para um modelo de reserva, tratamento de erro.
• Metadados: acrescentados automaticamente. Entre eles: wa_id (número do lead), lead_id, lead_name, lead_kanban_stage (coluna), zatten_thread_id (id da conversa na Zatten, o mesmo da API e dos webhooks), attendant_id (o projeto), agent_version e thread_id (id interno do serviço do agente, que agrupa as respostas na aba Threads).

As conversas do chat de teste também são enviadas, se a versão testada tiver o monitoramento ligado.

​

Achar a conversa de um lead

Abra o projeto no LangSmith e vá na aba Threads: cada linha é uma conversa, com a primeira e a última mensagem, número de respostas, tokens e custo. Para achar uma conversa específica, filtre pelos metadados do trace (em Filter → Metadata). Os mais úteis: Comece pelo wa_id quando você só tem o número do lead. Use o zatten_thread_id quando já tem a conversa vinda da API (GET /leads/{numero}/threads) ou de um webhook.

​

Ler um trace passo a passo

Abra um trace. À esquerda fica a árvore de passos; ao clicar num passo, a direita mostra entrada, saída, metadados, tempo e tokens.

​

Por que o agente errou?

Depois de corrigir, repita a mensagem do lead no chat de teste e compare os dois traces.

​

Custo por conversa

O LangSmith calcula o custo de cada chamada a partir dos tokens e de uma tabela de preços por modelo. A aba Threads mostra o custo de cada conversa; as estatísticas do projeto, o total do período. Ver Cost tracking.

• Modelo sem preço na tabela = custo zerado. A tabela já vem com a maior parte dos modelos da OpenAI, Anthropic e Gemini. Para modelos pelo OpenRouter com outro nome, cadastre o preço em Settings → Model Pricing (no LangSmith), com o preço por milhão de tokens de entrada e de saída que está na página do modelo no OpenRouter.
• Preço novo não recalcula o passado. Cadastrar ou mudar um preço vale só para os traces enviados depois.
• O custo do LangSmith é estimativa. A conta que vale é a do provider (OpenAI ou OpenRouter).

Para transformar isso em custo por atendimento e por mês, use o roteiro de Estimar o custo de IA.

​

Extrair dados pela API

Tudo o que aparece na tela sai pela API do LangSmith, com a mesma chave. Útil para relatórios por cliente, para o assistente da agência analisar conversas, ou para juntar custo de vários projetos.

​

Avaliar o agente

Além de investigar erro, o LangSmith ajuda a medir qualidade de forma repetível:

• Datasets a partir de traces: marque respostas boas e ruins e salve como exemplos. Viram a bateria de casos para conferir antes de publicar uma mudança.
• Avaliação automática: um modelo julga as respostas (ex.: “seguiu o tom?”, “ofereceu o agendamento?”), em traces novos ou num dataset.
• Revisão humana: filas para alguém da agência ler e anotar conversas.

O agente roda dentro da Zatten, então o teste de uma mudança continua sendo feito no chat de teste, com as mensagens do dataset. Ver Evaluation.

​

Pelo MCP

O monitoramento fica em langchain.config.settings.tracing. Escrever o bloco cria uma versão não publicada.

• O config enviado substitui o config inteiro. Se settings.tracing não vier, o monitoramento volta ao padrão (desligado). Mande sempre o config completo, como veio do get_template.
• Dentro de tracing, a chave já gravada é mantida só quando api_key não vem. "api_key": "" grava vazio por cima e o monitoramento para. Omita o campo ou devolva intacto o valor do get_template.
• get_template devolve a chave preenchida. Nunca mostre na conversa.

​

Armadilhas

• Ligado sem chave não envia nada. O painel avisa: “O monitoramento está ligado sem API Key, então nada é enviado.”
• Esquecer de publicar. Ligar e salvar não basta; só a versão publicada envia dados das conversas reais.
• Nome de projeto diferente cria outro projeto. Um erro de digitação espalha os traces em dois projetos.
• Conta fora dos EUA sem endpoint. A chave não é reconhecida e nada chega.
• Custo zerado. O modelo não está na tabela de preços do LangSmith; cadastre.
• Retenção. O LangSmith guarda os traces por um tempo que depende do plano. Para histórico longo, exporte pela API. Ver langchain.com/pricing.
• Dados pessoais. Quem tem acesso ao projeto do LangSmith lê as conversas.

​

Para saber mais

• Testar o agente
• Logs (o que aconteceu antes do agente: entrega, mídia, erros da Meta)
• Estimar o custo de IA
• Referência do config do agente
• LangSmith: observabilidade, início rápido, tracing com LangChain, threads, custos, avaliação, API, preços
• Termos para buscar: “LangSmith tracing”, “LangSmith threads”, “LangSmith cost tracking”, “LangSmith list_runs filter metadata”, “LLM observability”, “LLM-as-judge”.