Testes e Simulações

Testar agentes é uma capacidade de primeira classe da framework, e não um pormenor deixado para o fim. O Agent-Lab inclui dois harnesses complementares que podem ser utilizados tanto para validar a própria framework como para validar os agentes construídos sobre ela:

• Testes de integração exercitam o sistema contra infraestrutura real (Postgres, Redis, Keycloak, embeddings, Chrome headless) iniciada a pedido com testcontainers — abrangendo serviços externos, operações de base de dados, pesquisa vetorial e endpoints da API.
• Simulações de agentes avaliam o comportamento dos agentes de ponta a ponta contra LLM reais, com pontuação atribuída por um LLM-as-judge e acompanhamento ao longo do tempo no Langfuse e no LangWatch.

A configuração principal dos testes de integração encontra-se em tests/conftest.py; adapte-a ao seu ambiente.

Nota: os testes de integração e as simulações efetuam chamadas reais a serviços externos e podem implicar custos. Execute-os num ambiente controlado e monitorize a utilização.

Testes de integração

Requer Docker (ou outro runtime de containers) — a suite aprovisiona containers reais através do 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 demorar vários minutos — as imagens Docker e os modelos de embeddings são transferidos uma única vez. A cobertura de agent_lab/ é imposta na CI (SonarCloud).

Os projetos gerados a partir do scaffold seguem o mesmo modelo: tests/ contém smoke tests sem containers e, opcionalmente, uma suite com testcontainers.

Simulações de agentes

As simulações de agentes de ponta a ponta encontram-se em tests/simulation/ e chamam fornecedores de LLM reais. Estão marcadas como agent_test e são excluídas por predefinição; para as executar:

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

Três vertentes complementares partilham os helpers de arranque dos agentes, o juiz e as definições de conjuntos de dados em tests/simulation/datasets/:

• tests/simulation/scenario/ — simulações conversacionais com a framework langwatch-scenario: um simulador de utilizador conduz o agente enquanto um agente juiz pontua a interação.
• tests/simulation/langfuse/ — experiências orientadas por conjuntos de dados com os datasets do Langfuse. Cada execução sincroniza as definições dos conjuntos de dados, invoca o agente para cada item, pontua o resultado com um LLM-as-judge do lado do cliente e regista a execução e as pontuações no Langfuse para comparação ao longo do tempo. É ignorada automaticamente quando LANGFUSE_BASE_URL (ou o descontinuado LANGFUSE_HOST), LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY não estão definidos.
• tests/simulation/langwatch/ — as mesmas experiências replicadas no LangWatch através de langwatch.experiment, registando a pontuação do juiz por item. As definições são sincronizadas de forma idempotente num único dataset consolidado simulations (uma coluna dataset identifica a definição de origem, uma vez 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 definidos.

Os agentes de referência abrangidos pelas várias vertentes: coordinator-planner-supervisor, react RAG, visão/documentos, automação de browser, memorandos de voz e adaptive RAG.

Configuração dos LLM do juiz e dos agentes

O juiz (e o simulador de utilizador dos cenários) utilizam IDs de modelo litellm contra qualquer endpoint compatível com a API da OpenAI:

Os agentes em teste são executados num LLM predefinido servido por qualquer endpoint compatível com OpenAI (por exemplo, um servidor de inferência na rede local), aprovisionado por teste por tests/simulation/common/llm_factory.py. A exceção é o agente de memorandos de voz, que continua a utilizar a OpenAI (necessita de entrada de áudio no chat). Os embeddings continuam a utilizar o fallback EMBEDDINGS_ENDPOINT (o container Ollama de teste que serve bge-m3), em correspondência com o dump do pgvector. O endpoint tem de suportar tool calling / output estruturado para as suites baseadas em supervisor (automação de browser, supervisor):

Configurar as plataformas de avaliação

make test_simulations (e os targets de cada vertente) executam primeiro o passo sync_simulation_evals, que replica as definições dos conjuntos de dados em todas as plataformas configuradas. Para aprovisionar também a configuração de avaliação do lado do servidor no Langfuse (uma ligação 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 secção Evaluations do Langfuse), execute:

uv run python tests/setup_simulation_evals.py

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