O que é LangWatch Scenario?
Scenario, da empresa de observabilidade de LLM LangWatch, testa um agente conversando com ele. Você descreve uma situação em linguagem comum; um UserSimulatorAgent escreve as mensagens do usuário, seu agente responde por um único adaptador call(), e um JudgeAgent confere a conversa com seus critérios a cada turno e a encerra com um veredito. Os roteiros podem misturar mensagens fixas, mensagens geradas, asserções sobre chamadas de ferramentas e resultados de ferramentas simulados, e um RedTeamAgent troca o usuário simulado por um atacante de vários turnos com escalada no estilo Crescendo.
Os testes rodam como testes comuns de pytest (Python) ou vitest (TypeScript); Go aparece na lista, mas não está documentado no README. Agentes de voz podem ser testados com adaptadores para ElevenLabs, OpenAI Realtime, Twilio, Pipecat e Gemini Live, com áudio injetado, ruído de fundo e números de latência p50 e p95. Um cache_key faz o usuário simulado repetir as mesmas entradas entre execuções.
O repositório tem cerca de 1.000 estrelas e licença Apache-2.0. O simulador e o juiz precisam de uma chave de LLM (os exemplos usam por padrão openai/gpt-4.1-mini); uma chave da LangWatch é opcional e acrescenta uma visão ao vivo das execuções.
LangWatch Scenario vale a pena?
Avaliações de prompt único não veem como os agentes falham. Um agente pode responder bem à primeira pergunta e esquecer uma restrição no quarto turno, ou chamar a ferramenta errada quando o usuário muda de ideia. O Scenario testa isso simulando a conversa inteira, e sua principal conquista é fazer isso parecer qualquer outro teste da suíte: uma função de pytest ou vitest com uma descrição, uma lista de critérios para o juiz e um assert sobre o resultado.
O modelo de roteiro é o ponto mais forte. Você pode deixar o simulador no piloto automático até max_turns, ou fixar a primeira mensagem, injetar um resultado de ferramenta simulado, verificar que uma ferramenta específica foi chamada e então deixar o LLM continuar. Essa mistura mantém os testes focados no comportamento que importa, e não no que o simulador resolver dizer. O suporte a voz vai além dos concorrentes de código aberto, com testes de interrupção e percentis de latência.
O porém: dois modelos movem cada teste, e ambos custam tokens e ambos variam. Guardar o usuário simulado em cache com um cache_key, e envolver as chamadas LLM do seu próprio agente com @scenario.cache(), devolve a repetibilidade, mas um prompt alterado invalida o cache. Mesmo testes só de voz precisam de uma chave da OpenAI, porque o simulador e o juiz são modelos de texto por padrão. O projeto é pequeno, cerca de 1.000 estrelas com 165 issues abertas, e o README tem erros visíveis, como uma seção de voz que cita o nome de pacote errado.
A nuvem da LangWatch é opcional. Sem chave, os resultados ficam no seu terminal; com uma, o nível gratuito Developer permite 3 simulações, então equipes que querem um painel compartilhado vão parar no Growth a €29 por assento.
O Scenario funciona melhor ao lado de uma biblioteca de avaliação existente do que no lugar dela: Giskard ou DeepEval para métricas e varreduras, Scenario para as conversas cujos problemas só aparecem ao longo de vários turnos.
Onde ele se destaca
Um desenvolvedor criando um agente de reservas para um grupo de restaurantes
Garantir que o agente continue perguntando o número de pessoas quando o usuário muda a data no meio da conversa
Escreva um cenário em que o usuário simulado muda de planos no terceiro turno e dê ao juiz o critério de que o número de pessoas seja confirmado antes da reserva; rode na CI com um cache_key para que as falhas se reproduzam.
Uma equipe de IA de voz em uma startup de telemedicina de 30 pessoas
Verificar se o agente telefônico aguenta ruído de fundo e interrupções
Use o adaptador do Twilio ou do ElevenLabs, injete ruído de café a 0,3 e uma interrupção no meio da frase, e acompanhe a latência p95 entre execuções; uma chave da OpenAI continua necessária para o simulador e o juiz.
Antes de decidir
- Configuração
- uv add langwatch-scenario pytest, ou pnpm install @langwatch/scenario vitest; defina OPENAI_API_KEY, escreva um adaptador com um único método call() e rode o arquivo de teste.
- Integrações
- pytest e vitest; LiteLLM e o Vercel AI SDK nos exemplos; agentes já conectados à LangWatch dispensam adaptador; adaptadores de voz para ElevenLabs, OpenAI Realtime, Twilio Media Streams, Pipecat e Gemini Live.
- Dados e privacidade
- Roda localmente; as conversas vão ao provedor de LLM configurado para o simulador e o juiz, e à LangWatch só se uma LANGWATCH_API_KEY estiver definida. O cache fica em ~/.scenario/cache.
- Custo em escala
- A biblioteca é gratuita; o custo são dois LLMs por turno por teste. O LangWatch Growth custa €29 por assento principal por mês com 200k eventos, depois €5 por 100k, e cada passo de simulação conta como um evento.
- Limites
- max_turns limita uma conversa; adaptadores de voz para LiveKit, Vapi e WebRTC genérico estão planejados, não lançados.
O que é bom
- Testes de agentes com vários turnos escritos como testes comuns de pytest ou vitest
- Roteiros misturam turnos fixos e simulados, asserções sobre ferramentas e mocks
- Agente de red team com escalada de vários turnos no estilo Crescendo
- Adaptadores de voz com injeção de ruído e percentis de latência
- Cache para execuções repetíveis
O que não é
- Chamadas LLM do simulador e do juiz custam tokens a cada execução
- Resultados variam entre execuções sem cache
- Go listado, mas sem documentação
- Projeto pequeno com 165 issues abertas e erros no README
Ideal para
Equipes que constroem agentes de chat ou de voz e querem testes de regressão no nível da conversa no executor de testes que já usam.
Alternativas ao LangWatch Scenario
LangWatch Scenario: perguntas frequentes
- LangWatch Scenario vale a pena?
- Scenario é o jeito mais claro de escrever testes de agentes com vários turnos como testes unitários comuns, desde que você aceite que um LLM de cada lado torna cada execução um pouco diferente e um pouco cara. Damos nota 3.9 de 5.
- Quanto custa LangWatch Scenario?
- Gratuito e de código aberto (Apache-2.0); você paga os tokens do simulador e do juiz. Nuvem LangWatch opcional: Developer €0 (50k eventos, 3 simulações); Growth €29 por assento principal por mês com 200k eventos, depois €5 por 100k.
- Quais são as desvantagens de LangWatch Scenario?
- Chamadas LLM do simulador e do juiz custam tokens a cada execução; resultados variam entre execuções sem cache; go listado, mas sem documentação; projeto pequeno com 165 issues abertas e erros no README.
- Para quem LangWatch Scenario é indicado?
- Equipes que constroem agentes de chat ou de voz e querem testes de regressão no nível da conversa no executor de testes que já usam.
- Quanto custa LangWatch Scenario para uma equipe ou em produção?
- A biblioteca é gratuita; o custo são dois LLMs por turno por teste. O LangWatch Growth custa €29 por assento principal por mês com 200k eventos, depois €5 por 100k, e cada passo de simulação conta como um evento.
- LangWatch Scenario é seguro para dados da empresa?
- Roda localmente; as conversas vão ao provedor de LLM configurado para o simulador e o juiz, e à LangWatch só se uma LANGWATCH_API_KEY estiver definida. O cache fica em ~/.scenario/cache.
- Quais são as melhores alternativas ao LangWatch Scenario?
- As alternativas mais próximas que analisamos são Giskard, DeepEval, promptfoo e Langfuse.
Respostas verificadas em 6 de nov. de 2026.