LangSmith Explicado: Depuração e Avaliação de Agentes LLM

Introdução

Construir agentes autónomos com LLMs pode ser uma experiência frustrante e pouco confiável. Os prompts podem gerar resultados diferentes a cada execução, as ferramentas podem falhar silenciosamente, e os modelos podem criar informações falsas ou entrar em loops sem indícios claros. O LangSmith é uma plataforma para instrumentar, depurar, avaliar e monitorizar aplicações com LLM, para superar estes desafios e fornecer visibilidade total sobre o comportamento do seu agente. Neste tutorial, vamos percorrer um ciclo típico de fiabilidade de um agente: instrumentar um agente com rastreio, depurar execuções do agente automática e manualmente, avaliar o seu desempenho, iterar sobre os prompts e, finalmente, monitorizar o agente em produção. No final, deverá compreender o que é o LangSmith, como pode ajudar e como o utilizar para construir agentes de IA mais fiáveis.

Principais Conclusões

• A observabilidade é fundamental para a fiabilidade do agente: Com o rastreio da LangSmith, cada chamada de LLM, invocação de ferramenta e passo intermédio do raciocínio é observável, permitindo que compreenda por que um agente tomou determinada ação em vez de ter de a inferir a partir dos registos.
• As traces transform a depuração em análise: As traces estruturadas permitem-lhe inspecionar e diagnosticar metodicamente falhas de prompt, falhas de ferramentas, problemas de recuperação, erros de orquestração e corrigir o ponto exato da falha.
• A avaliação permite iteração segura: O fluxo de trabalho de avaliação baseado em dados da LangSmith (disponível tanto offline como online) permite-lhe medir a qualidade da sua aplicação, comparar versões de prompts/modelos e detetar regressões antes de lançar quaisquer alterações para produção.
• Engenharia de prompts torna-se disciplinada: O Prompt Playground e a versão de prompts transformam os prompts num ativo de primeira categoria, rastreável. Isto permite colaborar em prompts, garantir a reproducibilidade e controlar quando e como as alterações são aplicadas em produção.
• O feedback humano completa o ciclo: Filas de anotação (de execução única e pareadas) permitem-lhe tirar partido do julgamento humano em larga escala, melhorar os avaliadores e garantir qualidade onde as métricas automatizadas falham.

O que é o LangSmith (e quando vale a pena usá-lo)

LangSmith é um conjunto de ferramentas completo para construir, depurar, testar, avaliar e implementar as suas aplicações impulsionadas por LLM. Usando o LangSmith, pode:

• Rastreie cada pedido (capture cada passo do raciocínio de um agente).
• Avalie o seu resultado (certifique-se de que o seu agente está a gerar qualidade).
• Itere os seus prompts com controlo de versões.
• Gerir as implementações dos seus agentes.

Ao contrário de algumas das ferramentas de observabilidade, que muitas vezes estão fortemente ligadas a um determinado framework de aplicação LLM, o LangSmith é independente de framework. Pode usá-lo com LangChain, LangGraph ou outro código personalizado. Isto significa que não precisa de construir o seu agente no LangChain para aproveitar as funcionalidades de rastreio e avaliação do LangSmith.

É útil em qualquer caso em que os prompts chamam outras ferramentas ou APIs, ou está a lidar com raciocínio em vários passos, ou qualquer situação em que a reprodutibilidade e a depuração sejam importantes. Basicamente, se já ultrapassou o limite de declarações de registo simples e quer ser capaz de entender porque é que o seu agente fez o que fez, então deve dar uma olhada no LangSmith.

O Problema de Depuração de Agentes que o LangSmith Resolve

Desenvolver agentes autónomos é desafiante porque os agentes frequentemente falham de formas subtis e não intuitivas. Uma pequena alteração num prompt ou uma resposta não determinística de uma chamada API de uma ferramenta pode alterar drasticamente uma cadeia de raciocínio. Logs e métricas padrão não são suficientes para compreender as ações de um agente; pode-se ver um agente retornar um resultado incorreto ou sofrer um timeout, mas a origem da falha não é imediatamente óbvia. O agente usou a ferramenta errada para a tarefa? Faltava contexto no seu prompt? Uma chamada de LLM introduziu um erro subtil que se manifestou mais tarde? Estes são os tipos de questões que os rastos do LangSmith podem ajudar a responder.

Depurar agentes sem rastos detalhados pode transformar-se num jogo de adivinhação. Os agentes podem falhar silenciosamente ao alucinar ou ficar presos num ciclo, deixando-o a reproduzir problemas às cegas. O LangSmith resolve isto ao registar cada passo da jornada do agente (todas as chamadas LLM, invocações de ferramentas, prompts intermédios, etc.) numa linha temporal estruturada chamada rasto. Examinar um rasto permite ver exatamente o que correu mal.

Exemplo: Suponha que tenha um agente que utiliza uma ferramenta de pesquisa para obter informações. Se o agente fornecer uma resposta incorreta, o problema pode ser que: (1) a ferramenta de pesquisa devolveu uma resposta incorreta ou nenhum resultado (falha da ferramenta), (2) o LLM não utilizou os resultados da pesquisa e inventou uma resposta (falha de prompt/raciocínio), ou (3) a lógica do agente não chamou a ferramenta quando deveria (falha de orquestração).

Uma rastreabilidade LangSmith incluiria cada passo: a consulta e o resultado da chamada à API de pesquisa, o prompt do agente construído com esse resultado, a resposta do LLM, e assim por diante. Desta forma, pode ver imediatamente onde a cadeia falhou em seguir os caminhos esperados.

Início Rápido: Rastrear uma Execução de Agente (Exemplo em Python)

Bem-vindo a um breve exemplo sobre como usar o LangSmith para rastrear a execução de um agente. Vamos usar Python (o LangSmith também tem um SDK para JavaScript/TypeScript para rastreamento de forma semelhante, mas aqui mostramos Python). Neste exemplo, vamos instrumentar uma chamada LLM trivial e criar um rastreio na interface do LangSmith.

Pré-requisitos: Inscreva-se numa conta gratuita LangSmith (se ainda não o fez) e obtenha a sua chave de API. Também precisará da chave de API do seu fornecedor de LLM (ou seja, a chave de API da OpenAI). Instale os pacotes necessários:

pip install -U langsmith openai  # for this example

1. Ativar o Rastreamento LangSmith. O LangSmith funciona com o LangChain imediatamente – se já está a usar o LangChain, pode ativar o rastreamento com uma única variável de ambiente. No seu ambiente (ou no ficheiro .env), certifique-se de que estas estão definidas:

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>"

Isto garante que o rastreio do LangSmith está ativo e autenticado. (Se tiver mais de um espaço de trabalho LangSmith, defina também o LANGSMITH_WORKSPACE_ID de forma adequada.) Também pode definir estas variáveis a partir do Python usando o os.environ antes de inicializar qualquer LLM.

Importante: A flag LANGSMITH_TRACING=true deve ser definida antes de o seu código executar as chamadas LLM, para que o SDK possa interceptá-las.

2. Envolver ou Usar um Cliente LLM. Se estiver a usar as classes LLM do LangChain, não precisa de qualquer código especial para registar os rastos – apenas assegure-se de que a variável de ambiente está definida. Por exemplo, a usar o wrapper OpenAI do LangChain:

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "<your-langsmith-api-key>"
from langchain.chat_models import ChatOpenAI
llm = ChatOpenAI(model_name="gpt-3.5-turbo")  # This is LangChain's LLM wrapper
response = llm.predict("Hello, world!")
print(response)

Quando isto for executado, o LangChain irá detetar que o rastreio está ativado e irá registar a chamada ao LangSmith em segundo plano. Após executar este código, pode visitar a interface web do LangSmith e ver o rastreio (na lista de rastreios do projeto predefinido).

Se não estiver a usar o LangChain, pode instrumentar as suas chamadas LLM manualmente com o SDK do LangSmith. Por exemplo, se quiser rastrear chamadas à API da OpenAI diretamente, o LangSmith oferece um auxiliar wrap_openai:

from langsmith import wrappers
import openai
openai.api_key = os.environ["OPENAI_API_KEY"]
openai_client = wrappers.wrap_openai(openai.OpenAI())  # wrap the OpenAI client for tracing:contentReference[oaicite:14]{index=14}
# Now any call through openai_client will be traced:
result = openai_client.ChatCompletion.create(
   model="gpt-3.5-turbo",
   messages=[ {"role": "user", "content": "Hello, world?"} ]
)
print(result["choices"][0]["message"]["content"])

Aqui usamos langsmith.wrappers.wrap_openai para obter um cliente rastreado. O LangSmith tem wrappers semelhantes para outros fornecedores (Anthropic, etc.) também. Após executar este código, verá igualmente o rastreio completo no LangSmith, mostrando o pedido e a resposta do modelo.

3. Visualizar o Rasto. Mude para a interface LangSmith (aplicação web). Vá a Observabilidade/Rastros. Deverá ver uma nova entrada para a sua execução aí. Clique nela e verá uma visão estruturada da execução. Como o nosso exemplo era muito simples, pode haver apenas um nó de chamada LLM (com o prompt e a saída). Para uma cadeia/agente mais complexa, seria uma árvore de todos os subpassos (por exemplo, o processo de pensamento de um Agente e cada chamada de ferramenta). Pode inspeccionar tempos, entradas/saídas e até partilhar rastros, adicionar anotações, etc. Esta visibilidade imediata ajuda-o a saber com certeza que tudo funcionou. Se não funcionou (por exemplo, algum erro na cadeia), verá exatamente onde e porquê.

Dica: Se estiver a correr em produção, talvez não queira rastrear todas as execuções (para poupar custos). O LangSmith suporta amostragem de rastreios ou a ativação/desativação do rastreio no código. Por exemplo, pode ativar o rastreio apenas para uma percentagem de pedidos ou para sessões específicas (definindo a variável de ambiente dinamicamente ou com o SDK de configuração do LangSmith). Para desenvolvimento e depuração, ativar globalmente (como acima) é o caminho mais simples.

Traços de Leitura

Uma vez que tenha rastos, o próximo passo é diagnosticar problemas. Um rasto LangSmith é um pouco como um registo de experiências – é uma forma de categorizar falhas e identificar padrões. Aqui estão alguns modos de falha comuns e os padrões que criam nos rastos:

Pensa numa trace como um registo de investigação. Categoriza cada problema (prompt vs ferramenta vs outro), mede o seu impacto (deu erro ou apenas reduziu a qualidade da resposta?), e vais saber exatamente o que precisa ser corrigido. Inputs, prompts e ordem das ferramentas são explícitos e auditáveis com LangSmith; mutações de memória/estado são explícitas; latência, custo e caminhos de erro são quantificáveis.

Fluxo de Trabalho de Avaliação: Conjuntos de Dados, Avaliadores e Experimentos

O rastreio diz-lhe o que aconteceu durante uma execução única. A avaliação diz-lhe quão bons são esses resultados, especialmente quando precisa de medir a qualidade através de várias execuções ou comparar diferentes versões do seu agente. O LangSmith tem um fluxo de trabalho de avaliação completo para suportar tanto os testes offline como a monitorização online da qualidade da sua aplicação LLM.

Avaliação Offline vs Online: O LangSmith suporta ambos os modos. A avaliação offline é o que se faz antes de implementar alterações - prepara-se um conjunto de dados com exemplos de entradas (e, opcionalmente, saídas esperadas), e depois executa-se o agente com todos eles para ver o seu desempenho. Isto é ótimo para detetar regressões e comparar versões de prompts/modelos num ambiente controlado. A avaliação online, por outro lado, é realizada em produção - avalia continuamente as interações reais dos utilizadores à medida que acontecem, para monitorizar a qualidade com dados em tempo real. Ambos são úteis: a avaliação offline é como testes unitários/de integração para o seu agente, e a avaliação online é como monitorização em tempo real ou testes canário.

O fluxo de trabalho de avaliação típico na LangSmith é assim:

1. Criar um Conjunto de Dados: Uma coleção de casos de teste para o seu agente. Estes podem ser recolhidos de falhas anteriores (registos do seu agente a fornecer respostas incorretas), exemplos sintéticos que considere desafiantes, ou perguntas de utilizadores que deseja garantir que estão cobertas. No LangSmith, um conjunto de dados é simplesmente um conjunto de pares de entrada-saída (ou apenas entradas, se não tiver um resultado "verdadeiro"). Pode criar e gerir conjuntos de dados utilizando a interface ou o SDK. Por exemplo, em Python:

from langsmith import Client
client = Client()
dataset = client.create_dataset("MathQA set", description="Simple math Q&A tests")
client.create_examples(dataset.id, examples=[
   {"inputs": {"question": "What is 2+2?"}, "outputs": {"answer": "4"}},
   {"inputs": {"question": "What is the capital of France?"}, "outputs": {"answer": "Paris"}}
])

Isto criaria programaticamente um conjunto de dados com dois exemplos de perguntas e respostas. (Também poderia carregar conjuntos de dados a partir de um CSV/JSON ou criá-los na interface de utilizador.)

2. Definir Avaliadores: Avaliadores são funções ou modelos que avaliam a saída do seu agente para cada exemplo. O LangSmith vem com alguns avaliadores incorporados e suporta a criação de avaliadores personalizados. Os tipos comuns de avaliadores incluem:

• Correcção (Verdade): A saída contém a mesma resposta de uma resposta de referência conhecida como correcta? (Para isto, é necessário ter saídas de referência no seu conjunto de dados.)
• Avaliação por Rubrica: função personalizada em Python ou heurística para verificar algo (por exemplo, «o resultado incluiu uma citação?»).
• LLM-como-Juiz: Utilize outro LLM para avaliar a qualidade do resultado. Por exemplo, uma função da OpenAI pode comparar o resultado com a referência e fornecer uma pontuação.
• Comparação Par a Par: Utilize isto quando tiver dois resultados (por exemplo, do modelo A vs. modelo B) e quiser determinar qual é melhor.

Pode anexar um ou vários avaliadores a um experimento. O LangSmith utiliza a biblioteca OpenEvals (os avaliadores open-source) para isso. Por exemplo, para usar um avaliador LLM-como-juiz para a correção, importaria um prompt como CORRECTNESS_PROMPT e faria:

from openevals.llm import create_llm_as_judge
from openevals.prompts import CORRECTNESS_PROMPT
judge = create_llm_as_judge(prompt=CORRECTNESS_PROMPT)

Como pode ver, este juiz pode então ser usado para avaliar cada resultado (efetivamente pergunta a um LLM «Esta resposta está correta em relação à referência?», devolvendo uma pontuação)*

3. Realizar um Experimento: Agora a parte divertida – execute o seu agente no conjunto de dados e recolha os resultados. Na interface do LangSmith, criaria um novo Experimento, selecionaria o conjunto de dados e a função alvo (o seu agente/cadeia) a executar, anexaria os avaliadores, etc. Se estiver a usar código, utilizaria Client.run_on_dataset ou algo semelhante.

client = Client()
# Assuming `target_fn` is your function that takes an input dict and returns an output dict
experiment = client.run_on_dataset(
   dataset_name="MathQA set",
   func=target_fn,
   evaluators=[judge]  # the evaluator we defined
)

Isto irá executar a sua target_fn para cada exemplo no conjunto de dados, registar os resultados e depois permitir que o(s) avaliador(es) pontuem cada resultado. O LangSmith manterá todos estes dados registados num objeto Experiment que poderá inspecionar.

Na interface do utilizador, executar um experimento irá mostrar uma tabela de resultados com atualização em tempo real – verá cada exemplo, a saída do modelo e as pontuações dos avaliadores. Isto é útil para identificar padrões (por exemplo, «o agente falha em todas as perguntas de matemática que envolvem divisão»).

4. Analisar Resultados: Depois de concluir o experimento, pode comparar e analisar as suas execuções no LangSmith. Ordene e filtre as execuções por pontuação, filtre exemplos (por exemplo, “mostrar-me exemplos onde a pontuação de corretude foi baixa”), compare dois experimentos se tiver realizado múltiplos (por exemplo, comparar Agente v1 vs Agente v2 no mesmo conjunto de dados), etc. Isto é útil tanto para avaliar diferentes versões/modelos de prompts como para criar “testes de regressão” (pode literalmente armazenar um “conjunto dourado” de exemplos e, depois, garantir que futuras versões não reduzam as pontuações desses).

5. Iterar Melhorias: Se a avaliação não for suficientemente boa, irá aprimorar o agente de alguma forma (melhorar os prompts, mudar exemplos, corrigir como o agente utiliza as ferramentas, etc.) e realizar novos experimentos.

Um fluxo de trabalho particularmente útil é o Prompt Playground (uma interface "sem código" no LangSmith) para realizar avaliações rápidas de diferentes variantes de prompts. O Playground permite carregar um conjunto de dados, experimentar diferentes modelos de prompt ou parâmetros do modelo e ver imediatamente as pontuações de avaliação.

Uma nota final – A avaliação nem sempre é feita com automação. Por vezes, as métricas automatizadas/juízes LLM não captam alguns aspetos importantes. É aqui que a revisão/avaliação humana entra – e o LangSmith também suporta isto através de filas de anotação, que veremos na próxima secção.

Humano-No-Ciclo: Filas de Anotação para Qualidade em Escala

Avaliadores automatizados são excelentes, mas, em algum momento, quererá uma avaliação humana para obter as pontuações mais precisas. As filas de anotação do LangSmith são uma forma simples e escalável de obter revisão humana para os resultados do seu agente. Pode colocar os resultados do modelo numa fila para serem revistos, e os anotadores humanos (você, colegas ou etiquetadores profissionais) podem avaliá-los com base numa grelha de avaliação pré-definida.

O LangSmith suporta dois estilos de filas de anotação:

• Filas de Anotação de Execução Única: Este estilo mostra uma saída (uma execução) de cada vez ao avaliador, juntamente com uma rubrica ou perguntas a responder sobre essa saída. Pode ser tão simples como «Esta resposta está factualmente correcta? (Sim/Não)» ou «Avalie a clareza da resposta de 1 a 5». O avaliador verá o contexto completo (prompt, saída e, possivelmente, uma resposta de referência se a tiver) e submeterá feedback para essa execução.
• Filas de Anotação Pareada (PAQs): Isto apresenta duas respostas lado a lado e pede ao avaliador para escolher qual é melhor (ou se são iguais) de acordo com determinados critérios. Isto é útil para testes A/B – por exemplo, quando tem a Versão A e a Versão B de um agente a responder à mesma pergunta e quer que um humano decida qual fez melhor. As comparações pareadas são também ótimas se quiser comparar um modelo ou prompt novo com um antigo, o que é um caso de uso comum para ajuste fino ou RLHF.

Quando usar cada um? Filas de execução única são boas para obter classificações absolutas ou rótulos categóricos nos resultados (ótimo se estiver a criar um conjunto de dados de pontuações humanas para treinar um avaliador, ou apenas a monitorizar a qualidade).

O método par-a-par é útil quando a qualidade relativa é mais importante, ou seja, quando se quer garantir que a nova versão é uma melhoria e se quer saber o quanto as pessoas a preferem. Na prática, muitas equipas usam o método par-a-par ao fazer modelagem de preferências ou aprendizagem por reforço a partir de feedback humano (RLHF). Isto deve-se ao facto de ser mais fácil para os humanos dizer "qual destes dois é melhor" do que atribuir uma pontuação absoluta.

LangSmith vs Alternativas: Como se Compara

O espaço de observabilidade/feedback de LLM está a evoluir, e surgiram várias ferramentas que se sobrepõem ao conjunto de funcionalidades do LangSmith. Aqui está uma breve comparação entre o LangSmith e algumas alternativas populares, juntamente com algumas dicas para selecionar a ferramenta certa para o seu caso de uso:

Perguntas Frequentes

P1: Preciso do LangChain para usar o LangSmith?

Não. O LangSmith é independente de framework. Pode usá-lo com o LangChain, LangGraph ou mesmo sem qualquer framework. Se já estiver a usar o LangChain, óptimo – o LangSmith integra-se com uma configuração mínima (basta definir as variáveis de ambiente e ele irá registar automaticamente as chains/agents por si). Se não estiver a usar um framework, pode traçar manualmente as chamadas ao LLM ou a lógica do agente com o SDK do LangSmith.

P2: Posso avaliar sugestões sem escrever código?

Sim. O LangSmith fornece um Prompt Playground e uma interface de utilizador para avaliação que permitem fazer muito sem programação. Por exemplo, pode criar um conjunto de dados e executar um experimento inteiramente a partir da interface web – basta preencher exemplos, selecionar um avaliador no menu suspenso e clicar em Iniciar.

P3: Qual é a diferença entre anotações de execução única e pares em LangSmith?

Na anotação de execução única, um revisor humano é apresentado com uma saída (uma execução) de cada vez e fornece feedback com base numa rubrica (por exemplo, avaliando a sua correção ou outras qualidades). Na anotação comparativa, o revisor vê duas saídas lado a lado (normalmente de duas versões diferentes do modelo para a mesma entrada) e é perguntado qual é melhor ou se são iguais. A execução única serve para avaliar uma saída isoladamente. A comparativa serve para comparar saídas.

P4: O que preciso definir para garantir que as chamadas do meu LLM sejam rastreadas pelo LangSmith?

A configuração crítica é ativar o rastreio através de variáveis de ambiente ou configuração. Isto pode ser feito com variáveis de ambiente ou através da configuração. A maneira mais simples é definir a variável de ambiente LANGSMITH_TRACING=true antes de executar a sua aplicação. Também deverá definir a sua chave de API (LANGSMITH_API_KEY) para que os dados fiquem associados à sua conta, e claro, quaisquer chaves de API de modelos (como OPENAI_API_KEY). Com LANGSMITH_TRACING=true, qualquer integração suportada (LangChain, etc.) começará a registar informações. Se as variáveis de ambiente não forem possíveis, o LangSmith também suporta a ativação programática – por exemplo, em Python:

from langsmith import Client
client = Client()
client.configure_tracing(True)

Este é um exemplo hipotético; a API real pode ser diferente, mas conceptualmente, pode ativá-la no código. Execute a sua cadeia/agente — deverá ver rastos na interface do LangSmith. Caso contrário, verifique se definiu as suas variáveis de ambiente no mesmo contexto em que o código está realmente a ser executado (e com o espaço de trabalho correto, se aplicável).

P5: O LangSmith é apenas para rastreamento ou também trata de implementações?

O LangSmith foi criado com observabilidade e avaliação em mente, mas também possui um módulo de Implementação. Pode implantar agentes como endpoints geridos através do LangSmith (eles chamam-nos de Servidores de Agentes) e obter escalabilidade, tempo de atividade e monitorização imediatamente disponíveis.

Conclusão

LangSmith ajuda você a evoluir o desenvolvimento de agentes de um processo de tentativa e erro para um fluxo de trabalho de engenharia. Com rastreamento, avaliação, versionamento de prompts e revisão humana, você pode diagnosticar falhas, medir melhorias e evitar que regressões cheguem aos utilizadores. O hábito central no desenvolvimento de agentes é o ciclo de confiabilidade do agente: rastrear cada execução, transformar falhas reais em conjuntos de dados, realizar experiências repetíveis usando avaliadores (augmented por humanos quando necessário), e apenas promover as melhores alterações de prompt/modelo através de versões lançadas. O rastreamento e monitorização das operações permitem receber alertas precoces sobre ocorrências de desvios, falhas de ferramentas, flutuações de latência e impactos financeiros inesperados. O LangSmith oferece uma solução estruturada para desenvolvedores de agentes que utilizam ferramentas ou seguem multi-etapas, e que priorizam a reprodutibilidade e a iteração disciplinada durante o desenvolvimento, do protótipo à produção.

Referências

• Documentos LangSmith
• O que é o LangSmith? Rastreio e depuração para LLMs
• Alternativa ao LangSmith? Langfuse vs. LangSmith
• Rastreamento LangSmith: Depuração de cadeias LLM
• Início rápido de rastreio
• Avaliação LangSmith
• Início rápido de avaliação
• Utilizar filas de anotações
• Conceitos de observabilidade
• O Guia Completo das Plataformas de Observabilidade de LLM em 2025
• OpenTelemetry para GenAI e o projeto OpenLLMetry

Obrigado por aprender com a comunidade Linux-Console.net.