Avaliando Deep Agents com LangSmith na AWS: o guia completo para garantir qualidade em agentes de IA
A Inteligência Artificial chegou a um ponto onde não basta mais criar um agente inteligente e torcer para que ele funcione bem em produção. Validar o comportamento desses sistemas antes de colocá-los no ar virou, sem exagero, um dos maiores desafios da área hoje. E o problema não é simples: agentes de IA são sistemas multi-etapas, não determinísticos, onde um erro lá no começo pode comprometer tudo que vem depois. Uma única chamada errada a uma ferramenta pode gerar um efeito cascata por todo o fluxo de trabalho.
É exatamente aí que entra a combinação de LangSmith rodando na AWS, uma stack poderosa que oferece o framework de avaliação necessário para capturar esses problemas cedo, rastreá-los em produção e melhorar continuamente a confiabilidade do seu agente ao longo de todo o ciclo de vida. Esse guia combina aprendizados do trabalho da LangChain sobre avaliação de deep agents e do guia da Anthropic sobre desmistificação de avaliações para agentes de IA.
Aqui você vai encontrar algo prático de verdade, desde os conceitos fundamentais que todo desenvolvedor precisa conhecer, até a implementação de cinco padrões de avaliação para Deep Agents, passando por testes offline com pytest e monitoramento em tempo real em produção. O exemplo central é um agente texto-para-SQL construído com o Amazon Bedrock, usando o modelo Amazon Nova 2 Lite, percorrendo todo o ciclo de desenvolvimento até a produção.
Conhecendo o Amazon Nova 2 Lite
Antes de mergulhar nos padrões de avaliação, vale entender o modelo que está no centro desse exemplo. O Amazon Nova 2 Lite é um modelo de raciocínio rápido e com bom custo-benefício, disponível no Amazon Bedrock. Ele suporta extended thinking com níveis configuráveis de orçamento computacional (baixo, médio e alto) e aceita entradas de texto, imagem, vídeo e documentos, com uma janela de contexto de 1 milhão de tokens. O Nova 2 Lite se dá bem com tarefas como seguir instruções, chamadas de função e geração de código, o que o torna uma escolha natural para cargas de trabalho baseadas em agentes, como o agente texto-para-SQL usado neste post.
Por que avaliar agentes de IA é tão diferente de testar software comum
Quem já trabalhou com testes de software tradicional sabe que existe uma lógica relativamente clara: você dá uma entrada, espera uma saída determinística e verifica se o resultado bate com o esperado. Mas quando o assunto são agentes de Inteligência Artificial, essa lógica vai por água abaixo quase que completamente. Esses sistemas não seguem um caminho fixo. Eles raciocinam, tomam decisões intermediárias, consultam ferramentas externas, interpretam contextos ambíguos e geram respostas que podem variar a cada execução, mesmo com a mesma entrada.
Três propriedades tornam a avaliação de agentes fundamentalmente diferente:
- Não-determinismo: o comportamento do agente varia entre execuções. A mesma tarefa pode ter sucesso 90% das vezes e falhar em 10%. Um resultado único de passou/falhou não diz muita coisa. Você precisa de múltiplas tentativas para estimar a performance real. Duas métricas ajudam: pass@k mede a probabilidade de pelo menos um sucesso em k tentativas, enquanto pass^k mede a probabilidade de que todas as k tentativas tenham sucesso.
- Propagação de erros: em um agente multi-etapas, um equívoco no passo 3 pode se propagar por todos os passos seguintes. Um agente texto-para-SQL que identifica o schema errado no início vai construir um JOIN incorreto, produzindo resultados errados na resposta final. Avaliar apenas a saída final não revela onde as coisas deram errado.
- Soluções criativas: modelos de fronteira às vezes encontram abordagens válidas que os designers da avaliação não anteciparam. Isso significa que a avaliação precisa ser flexível o suficiente para reconhecer caminhos alternativos que ainda assim produzem resultados corretos.
Terminologia essencial para entender avaliação de agentes
Antes de entrar nos padrões, é importante alinhar o vocabulário:
- Task (Tarefa): um teste individual com entradas definidas e critérios de sucesso. Por exemplo, a pergunta Quantos clientes são do Canadá? com a resposta esperada de oito.
- Trial (Tentativa): uma execução individual de uma tarefa. Como as saídas dos modelos são não determinísticas, rodar múltiplas tentativas por tarefa produz resultados mais confiáveis.
- Grader (Avaliador): a lógica que pontua algum aspecto do desempenho do agente. Uma tarefa pode ter múltiplos avaliadores, cada um avaliando uma dimensão diferente.
- Transcript (Transcrição): o registro completo de uma tentativa, incluindo chamadas de ferramentas, passos de raciocínio, resultados intermediários e interações. No LangSmith, esse é o trace completo que você pode inspecionar para depuração.
- Outcome (Resultado): o estado final do ambiente ao fim de uma tentativa. O agente pode dizer a resposta é oito, mas o resultado real é se ele executou a query SQL correta contra o banco de dados.
- Evaluation harness: a infraestrutura que roda avaliações de ponta a ponta.
- Evaluation suite: uma coleção de tarefas projetadas para medir capacidades ou comportamentos específicos.
O que é possível avaliar em uma execução de agente
Para uma execução de agente, existem três categorias que podem ser testadas:
- Trajetória: a sequência de ferramentas chamadas e os argumentos específicos que o agente gerou. Ele explorou o schema? Usou o sql_db_query_checker antes de executar?
- Resposta final: a saída final retornada ao usuário. A resposta está correta? Está bem formatada?
- Outros estados: artefatos que o agente produziu, como arquivos escritos, planos de tarefas criados e resultados intermediários salvos.
Os três tipos de avaliadores e como combiná-los
Avaliações de agentes tipicamente combinam três tipos de avaliadores, e a chave para um design eficiente é escolher o mix certo para o seu caso de uso.
- E-BOOK GRATUITO
Um guia prático para avaliar, comparar e implementar inteligência artificial com clareza — sem desperdício de tempo ou dinheiro.
Pare de contratar ferramentas sem direção. Criamos um método estruturado para decidir qual IA realmente faz sentido para o seu negócio.
Entrega em PDF no seu e-mail · Sem spam · LGPD
🔒 Seus dados são protegidos conforme a LGPD. Você pode descadastrar a qualquer momento.
Avaliadores baseados em código
Usam lógica determinística para verificar condições específicas: correspondência de strings, padrões regex, testes binários de passa/falha, análise estática e verificação de chamadas de ferramentas. São rápidos, baratos, objetivos e fáceis de depurar. Quando você consegue expressar critérios de sucesso como código, faça isso. A limitação é que podem ser frágeis quando variações legítimas não casam com o padrão esperado. Um resultado formatado como oito clientes comparado com São oito pode falhar em uma correspondência estrita mesmo que ambos estejam corretos.
Avaliadores baseados em modelo (LLM-como-juiz)
Usam outro LLM para avaliar a saída do agente. Os métodos incluem pontuação baseada em rubrica, asserções em linguagem natural, comparação pareada e consenso multi-juiz. São flexíveis, escaláveis e capturam nuances, mas são não determinísticos, mais caros e precisam de calibração com avaliadores humanos. Uma dica importante: dê ao LLM juiz uma saída de escape, como retorne Desconhecido se não tiver informação suficiente, para evitar pontuações alucinadas.
Avaliadores humanos
Considerados o padrão-ouro para avaliações subjetivas de qualidade. São caros e lentos comparados às opções programáticas, mas essenciais para calibrar os avaliadores baseados em modelo. Use-os com parcimônia: calibre as rubricas do LLM-como-juiz contra o julgamento humano especializado inicialmente, e depois utilize revisão humana periodicamente para verificar se os avaliadores automatizados não desviaram.
Recomendação prática de combinação
Para um agente texto-para-SQL, a combinação ideal ficaria assim:
- Baseado em código: o agente chamou sql_db_query? A resposta contém o número correto? Comandos DML (INSERT, DELETE) foram executados?
- LLM-como-juiz: para consultas complexas onde o formato de saída varia. A análise está correta, completa e bem estruturada?
- Humano: verificações periódicas para garantir que a avaliação do LLM está alinhada com o julgamento especializado.
Avaliações de capacidade versus avaliações de regressão
Nem todas as avaliações servem ao mesmo propósito, e entender essa distinção é fundamental:
- Avaliações de capacidade perguntam o que esse agente consegue fazer bem? Devem mirar tarefas com as quais o agente atualmente tem dificuldade, dando à equipe uma meta clara. Comece com uma taxa de aprovação baixa e trabalhe para melhorá-la.
- Avaliações de regressão perguntam o agente ainda lida com o que costumava lidar? Devem ter uma taxa de aprovação próxima de 100%. Uma queda sinaliza que algo quebrou.
Conforme o agente amadurece, avaliações de capacidade que atingem altas taxas de aprovação podem ser promovidas para o conjunto de regressão. Tarefas que antes mediam ele consegue fazer isso? passam a medir ele ainda consegue fazer isso de forma confiável?
Os cinco padrões de avaliação para Deep Agents na prática
Deep agents são sistemas que usam planejamento, chamadas de ferramentas, backends de sistema de arquivos e carregamento progressivo de contexto para enfrentar tarefas complexas e multi-etapas. Eles quebram a suposição tradicional de que todo caso de teste pode ser executado pela mesma lógica de aplicação e pontuado pelo mesmo avaliador. A LangChain, ao desenvolver quatro aplicações sobre arquiteturas de deep agents, identificou os padrões que se aplicam amplamente.
Padrão 1: Lógica de teste customizada por caso
A avaliação tradicional de LLM trata todo ponto de dados de forma idêntica. Deep agents quebram essa suposição. Cada caso de teste pode ter seus próprios critérios de sucesso, e esses critérios podem envolver asserções específicas contra a trajetória e o estado do agente, não apenas a mensagem final. A integração do LangSmith com pytest suporta esse padrão, permitindo que você faça diferentes asserções sobre a trajetória, a mensagem final e o estado para cada caso de teste.
Padrão 2: Avaliações de passo único
Cerca de metade dos casos de teste da LangChain para deep agents foram avaliações de passo único: o que o agente decidiu fazer imediatamente após uma entrada específica? Isso é especialmente útil para validar pontos de decisão individuais. Regressões frequentemente ocorrem em pontos de decisão individuais, não ao longo de sequências completas de execução. Para um agente texto-para-SQL, uma avaliação de passo único pode verificar se a primeira ação do agente é explorar o schema do banco de dados, em vez de pular direto para escrever uma query. São os testes unitários dos agentes: rápidos, focados e eficientes em tokens.
Padrão 3: Turnos completos do agente
Enquanto avaliações de passo único testam decisões individuais, turnos completos mostram o quadro geral. Rode o agente de ponta a ponta em uma entrada e avalie tanto a trajetória quanto a resposta final. Um insight importante aqui: teste se certas ferramentas apareceram na trajetória, mas não exija uma ordem exata. O agente pode listar tabelas antes de obter o schema, ou ir direto ao schema. Ambos são válidos. Avalie o que o agente produziu, não o caminho exato que ele percorreu.
Padrão 4: Avaliações multi-turno
Alguns cenários exigem testar agentes em conversas de múltiplos turnos. Um usuário pergunta Quais são os 5 artistas mais vendidos? e depois complementa com Para o artista do topo, quantos álbuns ele tem? O desafio é que, se você codifica rigidamente uma sequência de entradas e o agente desvia do caminho esperado, as entradas subsequentes podem não fazer sentido. A solução é usar lógica condicional nos testes: se o turno 1 falhou, falhe antecipadamente em vez de continuar com dados incoerentes.
Padrão 5: Verificações de segurança e estado
Esse padrão vai além da correção e avalia se o agente opera dentro de limites seguros. Para o agente texto-para-SQL, a verificação mais crítica é garantir que nenhum comando DML (como INSERT, UPDATE, DELETE, DROP, ALTER ou TRUNCATE) seja executado. Também verifica se consultas complexas ativam o mecanismo de planejamento do agente e se a resposta final é substantiva o suficiente para ser útil ao usuário.
Exemplo prático: arquitetura do agente texto-para-SQL na AWS
O agente texto-para-SQL usado como exemplo é construído sobre o framework DeepAgents, que fornece planejamento, armazenamento em sistema de arquivos e carregamento progressivo de contexto sobre o LangGraph. Ele responde perguntas em linguagem natural sobre o banco de dados Chinook, um banco SQLite de exemplo que representa uma loja de mídia digital.
Para acompanhar o exemplo completo, você precisa de:
- Uma conta AWS com acesso ao Amazon Bedrock habilitado
- Uma conta LangSmith e uma chave de API
- Python 3.12 ou superior
- AWS CLI configurado com credenciais
- Pacotes necessários: deepagents, langchain-aws, langchain-community e pytest
O agente usa o Amazon Nova 2 Lite no Amazon Bedrock através do ChatBedrockConverse, e o rastreamento do LangSmith é automaticamente integrado à execução do LangGraph. Isso significa que cada chamada de ferramenta, passo de planejamento e decisão do agente é capturada como um trace sem necessidade de instrumentação manual.
Testes offline com pytest e a importância da automação
Um dos aspectos mais práticos dessa abordagem é a integração entre o LangSmith e o pytest. Usando o decorador @pytest.mark.langsmith, cada caso de teste é automaticamente registrado como um experimento no LangSmith com traces completos. Isso permite que os cinco padrões de avaliação sejam executados de forma automatizada dentro de pipelines de integração contínua, garantindo que nenhuma mudança no agente vá para produção sem passar por uma bateria completa de testes.
O que torna essa abordagem especialmente poderosa é que ela separa claramente dois momentos distintos do ciclo de desenvolvimento: o momento de experimentação, onde você ainda está construindo e ajustando o agente, e o momento de validação, onde você precisa de garantias objetivas e reproduzíveis sobre o comportamento do sistema. Para cada execução de teste, você consegue:
- Inspecionar traces completos: ver cada chamada de ferramenta, o passo de planejamento write_todos, cada invocação de sql_db_schema, as queries SQL reais executadas e a resposta final formatada.
- Acompanhar pontuações de feedback ao longo do tempo: as chamadas t.log_feedback() criam métricas que você pode visualizar em gráficos ao longo dos experimentos.
- Comparar experimentos: rode a mesma suíte de avaliação após uma mudança e compare os resultados lado a lado.
- Monitorar uso de tokens e latência: identifique quais etapas do agente são mais caras e onde concentrar esforços de melhoria.
Monitoramento em tempo real: do offline para o online em produção
Tudo construído até aqui, as cinco avaliações baseadas em pytest, roda offline, antes do deploy. Você organiza casos de teste, roda o agente contra eles e verifica as pontuações. Isso é essencial para desenvolvimento e testes de regressão. Mas o passo seguinte é monitorar o agente em produção, onde não existem saídas de referência. Usuários reais fazem perguntas que você nunca antecipou, o banco de dados pode mudar e casos de borda surgem que nenhum dataset curado captura.
O LangSmith suporta dois modos de avaliação que trabalham juntos ao longo do ciclo de vida do agente:
Receba o melhor conteúdo de inovação em seu e-mail
Todas as notícias, dicas, tendências e recursos que você procura entregues na sua caixa de entrada.
Ao assinar a newsletter, você concorda em receber comunicações da Método Viral. A gente se compromete a sempre proteger e respeitar sua privacidade.
- Avaliação offline: roda em datasets curados com saídas de referência, antes do deploy, para benchmarking, testes de regressão e testes unitários.
- Avaliação online: roda em traces de produção ao vivo, após o deploy, para monitoramento em tempo real e detecção de anomalias, usando apenas entradas e saídas sem respostas de referência.
Avaliadores online rodam automaticamente nos traces de produção. Nenhum deploy de código é necessário. Você os configura na interface do LangSmith, e eles pontuam cada trace (ou uma amostra) em tempo real.
Avaliador online de código: verificação de segurança SQL
Avaliadores de código são funções Python ou JavaScript determinísticas que rodam inline no LangSmith. São ideais para guardrails de segurança que precisam verificar cada trace de produção. Para o agente texto-para-SQL, a verificação mais crítica é garantir que o agente não execute comandos DML em produção.
Avaliador online LLM-como-juiz: qualidade da resposta
Como não existem saídas de referência em produção, esse é um avaliador livre de referência. O juiz avalia a consistência interna da resposta, a clareza e a completude aparente. Você configura uma taxa de amostragem, por exemplo 50% dos traces, para controlar custos, e mapeia as variáveis do prompt para as entradas e saídas da execução.
Avaliador online composto: pontuação geral de qualidade
Avaliadores compostos combinam múltiplas pontuações em uma métrica única, útil para dashboards e alertas. Para o agente texto-para-SQL, a configuração recomendada usa uma média ponderada onde segurança SQL tem peso 0.4, confiança de correção tem peso 0.3, clareza tem peso 0.15 e completude tem peso 0.15. Com essa pontuação composta, você pode filtrar traces problemáticos, criar gráficos de tendência de qualidade e configurar alertas quando a qualidade cai abaixo de um limite definido.
Fechando o ciclo: de falhas em produção a novos casos de teste
O monitoramento em produção também fecha o ciclo de melhoria contínua do agente. Quando o LangSmith identifica execuções problemáticas, elas podem ser facilmente adicionadas ao dataset de avaliação offline, enriquecendo os casos de teste com exemplos reais que o agente encontrou em produção e com os quais ele teve dificuldade. Isso cria um flywheel virtuoso onde o agente fica progressivamente melhor ao longo do tempo, não apenas porque o modelo base melhora, mas porque a equipe de desenvolvimento tem cada vez mais visibilidade sobre os pontos fracos do sistema e consegue endereçá-los de forma sistemática e baseada em dados concretos.
O loop entre avaliação offline e online é a chave para melhorar o comportamento do agente: falhas em produção se tornam casos de teste, casos de teste ajudam a prevenir falhas futuras, e métricas substituem adivinhação.
A combinação de LangSmith, AWS e os cinco padrões de avaliação para Deep Agents representa hoje um dos frameworks mais completos disponíveis para quem quer levar o desenvolvimento de agentes de Inteligência Artificial a sério, com a disciplina e o rigor que sistemas em produção real exigem.
Para explorar o exemplo completo em funcionamento, o repositório companion está disponível no GitHub da AWS. Para saber mais sobre os serviços utilizados, vale conferir a documentação do Amazon Bedrock para acesso gerenciado a modelos de fundação, do Amazon Nova para a família de modelos da AWS e do Amazon Bedrock Guardrails para adicionar controles de segurança aos seus agentes. 🚀
