Pruebas y simulaciones

Dos entornos de prueba: pruebas de integración con infraestructura real y simulaciones de agentes con LLM como juez

Probar agentes es una capacidad central del framework, no algo secundario. Agent-Lab incluye dos entornos de prueba complementarios que puedes usar tanto para validar el propio framework como para validar los agentes que crees sobre él:

Las pruebas de integración ponen a prueba el sistema contra infraestructura real (Postgres, Redis, Keycloak, embeddings, Chrome headless) que se levanta bajo demanda con testcontainers, y cubren servicios externos, operaciones de base de datos, búsqueda vectorial y endpoints de la API.
Las simulaciones de agentes evalúan el comportamiento de los agentes de principio a fin con LLM reales, con puntuaciones asignadas por un LLM como juez y con seguimiento a lo largo del tiempo en Langfuse y LangWatch.

La configuración principal de las pruebas de integración se encuentra en tests/conftest.py; personalízala según tu entorno.

Nota: las pruebas de integración y las simulaciones hacen llamadas reales a servicios externos y pueden generar costos. Ejecútalas en un entorno controlado y supervisa el uso.

Pruebas de integración

Requiere Docker (u otro entorno de ejecución de contenedores): la suite aprovisiona contenedores reales mediante 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%)

La primera ejecución puede tardar varios minutos: las imágenes de Docker y los modelos de embeddings se descargan una sola vez. La cobertura de agent_lab/ se exige en CI (SonarCloud).

Los proyectos generados replican este esquema: tests/ contiene pruebas de humo sin contenedores, además de una suite opcional con testcontainers.

Simulaciones de agentes

Las simulaciones de agentes de principio a fin se encuentran en tests/simulation/ y llaman a proveedores de LLM reales. Están marcadas como agent_test y se excluyen de forma predeterminada; ejecútalas con:

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

Tres vías complementarias comparten los helpers de arranque de agentes, el juez y las definiciones de conjuntos de datos en tests/simulation/datasets/:

tests/simulation/scenario/: simulaciones conversacionales con el framework langwatch-scenario: un simulador de usuario dirige al agente mientras un agente juez puntúa la interacción.
tests/simulation/langfuse/: experimentos basados en conjuntos de datos de Langfuse. Cada ejecución sincroniza las definiciones de los conjuntos de datos, invoca al agente por cada elemento, puntúa la salida con un LLM como juez del lado del cliente y registra la ejecución y las puntuaciones en Langfuse para compararlas a lo largo del tiempo. Se omite automáticamente cuando LANGFUSE_BASE_URL (o el obsoleto LANGFUSE_HOST), LANGFUSE_PUBLIC_KEY y LANGFUSE_SECRET_KEY no están definidas.
tests/simulation/langwatch/: los mismos experimentos con conjuntos de datos replicados en LangWatch mediante langwatch.experiment, que registra la puntuación del juez por elemento. Las definiciones se sincronizan de forma idempotente en un único conjunto de datos consolidado simulations (una columna dataset identifica la definición de origen, ya que el plan gratuito de LangWatch permite como máximo 3 conjuntos de datos por proyecto). Se omite automáticamente cuando LANGWATCH_ENDPOINT y LANGWATCH_API_KEY no están definidas.

Los agentes de referencia cubiertos en las distintas vías son: coordinator-planner-supervisor, RAG ReAct, visión/documentos, automatización de navegador, notas de voz y RAG adaptativo.

Configuración de los LLM del juez y de los agentes

El juez (y el simulador de usuario de scenario) usan ID de modelo de litellm contra cualquier endpoint compatible con la API de OpenAI:

Variable de entorno	Valor predeterminado	Propósito
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	ID de modelo de litellm que usa el LLM como juez
`SIMULATION_JUDGE_API_BASE`	valor predeterminado del proveedor	endpoint personalizado compatible con OpenAI para el modelo juez
`SIMULATION_JUDGE_API_KEY`	valor predeterminado del proveedor	clave de API para el endpoint personalizado

Los agentes bajo prueba se ejecutan con un LLM predeterminado servido por cualquier endpoint compatible con OpenAI (p. ej., un servidor de inferencia en la LAN), aprovisionado por prueba mediante tests/simulation/common/llm_factory.py. La excepción es el agente de notas de voz, que sigue usando OpenAI (necesita entrada de audio en el chat). Los embeddings siguen usando el respaldo EMBEDDINGS_ENDPOINT (el contenedor de Ollama de pruebas que sirve bge-m3), en correspondencia con el volcado de pgvector. El endpoint debe admitir llamadas a herramientas y salida estructurada para las suites basadas en supervisores (automatización de navegador, supervisor):

Variable de entorno	Valor predeterminado	Propósito
`SIMULATION_LLM_MODEL`	ninguno (obligatoria)	etiqueta del modelo que ejecuta las simulaciones (p. ej., `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	ninguno (obligatoria)	endpoint compatible con OpenAI que sirve el modelo
`SIMULATION_LLM_API_KEY`	`dummy-key`	clave de API, si el endpoint la requiere

Configuración de las plataformas de evaluación

make test_simulations (y los targets de cada vía) ejecutan primero el paso sync_simulation_evals, que replica las definiciones de los conjuntos de datos en cada plataforma configurada. Para aprovisionar también la configuración de evaluación del lado del servidor de Langfuse (una conexión de LLM para el modelo juez, un evaluador simulation_llm_as_judge y una regla de evaluación por cada conjunto de datos de simulación, visibles en la sección Evaluations de Langfuse), ejecuta:

uv run python tests/setup_simulation_evals.py

El script es idempotente y se puede volver a ejecutar sin riesgo.