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 de primer nivel 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 construyas sobre él:

Las pruebas de integración ejercitan el sistema contra infraestructura real (Postgres, Redis, Keycloak, embeddings, Chrome headless) que se levanta bajo demanda con testcontainers; 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 extremo a extremo con LLM reales, puntuado por un LLM como juez y monitorizado 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; adáptala a tu entorno.

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

Pruebas de integración

Requiere Docker (u otro entorno de ejecución de contenedores): la batería 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 la CI (SonarCloud).

Los proyectos generados con el scaffold siguen el mismo esquema: tests/ contiene pruebas de humo sin contenedores, además de una batería opcional con testcontainers.

Simulaciones de agentes

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

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

Tres líneas complementarias comparten los helpers de arranque de agentes, el juez y las definiciones de conjuntos de datos de 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 para cada elemento, puntúa la salida con un LLM como juez en el 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, registrando 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 líneas: coordinator-planner-supervisor, RAG react, visión/documentos, automatización del 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 IDs de modelo de litellm contra cualquier endpoint compatible con la API de OpenAI:

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

Los agentes sometidos a prueba se ejecutan sobre un LLM por defecto servido por cualquier endpoint compatible con OpenAI (p. ej., un servidor de inferencia en la LAN), aprovisionado para cada prueba por 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 Ollama de pruebas que sirve bge-m3), en consonancia con el volcado de pgvector. El endpoint debe admitir llamadas a herramientas / salida estructurada para las baterías basadas en supervisor (automatización del navegador, supervisor):

Variable de entorno	Valor por defecto	Finalidad
`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

Configurar las plataformas de evaluación

make test_simulations (y los targets de cada línea) ejecutan primero el paso sync_simulation_evals, que replica las definiciones de los conjuntos de datos en todas las plataformas configuradas. Para aprovisionar además la configuración de evaluación del lado del servidor de Langfuse (una conexión 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.