Testes e simulações

Testar agentes é um recurso de primeira classe do framework, e não algo deixado para depois. O Agent-Lab inclui dois harnesses complementares que você pode usar tanto para validar o próprio framework quanto para validar os agentes que você constrói sobre ele:

• Testes de integração exercitam o sistema contra infraestrutura real (Postgres, Redis, Keycloak, embeddings, Chrome headless) criada sob demanda com testcontainers — cobrindo serviços externos, operações de banco de dados, busca vetorial e endpoints da API.
• Simulações de agentes avaliam o comportamento dos agentes de ponta a ponta contra LLMs reais, pontuadas por um LLM como juiz e acompanhadas ao longo do tempo no Langfuse e no LangWatch.

A configuração principal dos testes de integração fica em tests/conftest.py; personalize-a para o seu ambiente.

Observação: os testes de integração e as simulações fazem chamadas reais a serviços externos e podem gerar custos. Execute-os em um ambiente controlado e monitore o uso.

Testes de integração

Requer Docker (ou outro runtime de containers) — a suíte provisiona containers reais via testcontainers.

make test_unit         # fast lane: boots the app with no infrastructure
make test_integration  # the full real-infrastructure suite
make test              # both, with coverage (gate: 90%)

A primeira execução pode levar vários minutos — as imagens Docker e os modelos de embeddings são baixados uma única vez. A cobertura de agent_lab/ é exigida no CI (SonarCloud).

Os projetos gerados pelo scaffold seguem o mesmo modelo: tests/ contém smoke tests sem containers, além de uma suíte opcional com testcontainers.

Simulações de agentes

As simulações de agentes de ponta a ponta ficam em tests/simulation/ e chamam provedores de LLM reais. Elas são marcadas como agent_test e desmarcadas por padrão; execute-as com:

make test_simulations
# or a single track:
make scenario_simulation
make langwatch_simulation
make langfuse_simulation

Três trilhas complementares compartilham os helpers de bootstrap dos agentes, o juiz e as definições de datasets em tests/simulation/datasets/:

• tests/simulation/scenario/ — simulações conversacionais usando o framework langwatch-scenario: um simulador de usuário conduz o agente enquanto um agente juiz pontua a interação.
• tests/simulation/langfuse/ — experimentos orientados a datasets usando datasets do Langfuse. Cada execução sincroniza as definições de datasets, invoca o agente para cada item, pontua a saída com um LLM como juiz no lado do cliente e registra a execução e as pontuações no Langfuse para comparação ao longo do tempo. É ignorada automaticamente quando LANGFUSE_BASE_URL (ou o obsoleto LANGFUSE_HOST), LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY não estão definidas.
• tests/simulation/langwatch/ — os mesmos experimentos com datasets espelhados no LangWatch via langwatch.experiment, registrando a pontuação do juiz por item. As definições são sincronizadas de forma idempotente em um único dataset consolidado simulations (uma coluna dataset identifica a definição de origem, já que o plano gratuito do LangWatch permite no máximo 3 datasets por projeto). É ignorada automaticamente quando LANGWATCH_ENDPOINT e LANGWATCH_API_KEY não estão definidas.

Os agentes de referência cobertos pelas trilhas: coordinator-planner-supervisor, react RAG, visão/documentos, automação de navegador, memos de voz e RAG adaptativo.

Configuração dos LLMs do juiz e dos agentes

O juiz (e o simulador de usuário do scenario) usam ids de modelo do litellm contra qualquer endpoint compatível com a API da OpenAI:

Os agentes sob teste rodam em um LLM padrão servido por qualquer endpoint compatível com a OpenAI (por exemplo, um servidor de inferência na LAN), provisionado por teste por tests/simulation/common/llm_factory.py. A exceção é o agente de memos de voz, que continua na OpenAI (ele precisa de entrada de áudio no chat). Os embeddings continuam usando o fallback EMBEDDINGS_ENDPOINT (o container Ollama de teste servindo bge-m3), compatível com o dump do pgvector. O endpoint precisa suportar tool calling / saída estruturada para as suítes baseadas em supervisor (automação de navegador, supervisor):

Configurando as plataformas de avaliação

make test_simulations (e os targets por trilha) executam primeiro a etapa sync_simulation_evals, que espelha as definições de datasets em todas as plataformas configuradas. Para também provisionar a configuração de avaliação no lado do servidor do Langfuse (uma conexão de LLM para o modelo juiz, um avaliador simulation_llm_as_judge e uma regra de avaliação por dataset de simulação — visíveis na seção Evaluations do Langfuse), execute:

uv run python tests/setup_simulation_evals.py

O script é idempotente e pode ser executado novamente com segurança.