Test e simulazioni · Agent-Lab

Due harness: test di integrazione su infrastruttura reale e simulazioni di agenti con LLM-as-judge

Testare gli agenti è una funzionalità di primo piano del framework, non un ripensamento. Agent-Lab include due harness complementari che puoi usare sia per validare il framework stesso sia per validare gli agenti che crei su di esso:

I test di integrazione mettono alla prova il sistema su infrastruttura reale (Postgres, Redis, Keycloak, embedding, Chrome headless) avviata su richiesta con testcontainers, coprendo servizi esterni, operazioni sul database, ricerca vettoriale ed endpoint dell'API.
Le simulazioni di agenti valutano il comportamento degli agenti end-to-end con LLM reali, con punteggi assegnati da un LLM-as-judge e monitorati nel tempo in Langfuse e LangWatch.

La configurazione principale dei test di integrazione si trova in tests/conftest.py; personalizzala in base al tuo ambiente.

Nota: i test di integrazione e le simulazioni effettuano chiamate reali a servizi esterni e possono generare costi. Eseguili in un ambiente controllato e monitora l'utilizzo.

Test di integrazione

Richiede Docker (o un altro container runtime): la suite crea container reali tramite 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 prima esecuzione può richiedere diversi minuti: le immagini Docker e i modelli di embedding vengono scaricati una sola volta. La copertura di agent_lab/ è verificata in CI (SonarCloud).

I progetti generati dallo scaffold seguono lo stesso schema: tests/ contiene smoke test senza container più una suite testcontainers facoltativa.

Simulazioni di agenti

Le simulazioni end-to-end degli agenti si trovano in tests/simulation/ e chiamano provider LLM reali. Sono contrassegnate con agent_test ed escluse per impostazione predefinita; eseguile con:

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

Tre track complementari condividono gli helper di bootstrap degli agenti, il giudice e le definizioni dei dataset in tests/simulation/datasets/:

tests/simulation/scenario/: simulazioni conversazionali che usano il framework langwatch-scenario: un simulatore di utente guida l'agente mentre un agente giudice valuta l'interazione.
tests/simulation/langfuse/: esperimenti basati su dataset che usano i dataset di Langfuse. Ogni esecuzione sincronizza le definizioni dei dataset, invoca l'agente per ogni elemento, valuta l'output con un LLM-as-judge lato client e registra esecuzione e punteggi in Langfuse per confrontarli nel tempo. Viene saltata automaticamente quando LANGFUSE_BASE_URL (o il deprecato LANGFUSE_HOST), LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY non sono impostate.
tests/simulation/langwatch/: gli stessi esperimenti sui dataset replicati in LangWatch tramite langwatch.experiment, registrando il punteggio del giudice per ogni elemento. Le definizioni vengono sincronizzate in modo idempotente in un unico dataset consolidato simulations (una colonna dataset identifica la definizione di origine, poiché il piano gratuito di LangWatch consente al massimo 3 dataset per progetto). Viene saltata automaticamente quando LANGWATCH_ENDPOINT e LANGWATCH_API_KEY non sono impostate.

Gli agenti di riferimento coperti dai vari track: coordinator-planner-supervisor, react RAG, visione/documenti, automazione del browser, memo vocali e adaptive RAG.

Configurazione degli LLM del giudice e degli agenti

Il giudice (e il simulatore di utente degli scenari) usa id di modello litellm con qualsiasi endpoint compatibile con l'API di OpenAI:

Variabile d'ambiente	Predefinito	Scopo
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	id del modello litellm usato dall'LLM-as-judge
`SIMULATION_JUDGE_API_BASE`	predefinito del provider	endpoint personalizzato compatibile con OpenAI per il modello giudice
`SIMULATION_JUDGE_API_KEY`	predefinito del provider	API key per l'endpoint personalizzato

Gli agenti sotto test vengono eseguiti su un LLM predefinito servito da qualsiasi endpoint compatibile con OpenAI (ad es. un server di inferenza nella LAN), predisposto per ogni test da tests/simulation/common/llm_factory.py. Fa eccezione l'agente dei memo vocali, che resta su OpenAI (richiede input audio in chat). Gli embedding continuano a usare il fallback EMBEDDINGS_ENDPOINT (il container Ollama di test che serve bge-m3), in linea con il dump pgvector. L'endpoint deve supportare tool calling / output strutturato per le suite basate sul supervisor (automazione del browser, supervisor):

Variabile d'ambiente	Predefinito	Scopo
`SIMULATION_LLM_MODEL`	nessuno (obbligatoria)	tag del modello che esegue le simulazioni (ad es. `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	nessuno (obbligatoria)	endpoint compatibile con OpenAI che serve il modello
`SIMULATION_LLM_API_KEY`	`dummy-key`	API key, se l'endpoint ne richiede una

Configurare le piattaforme di valutazione

make test_simulations (e i target dei singoli track) esegue prima il passaggio sync_simulation_evals, che replica le definizioni dei dataset su ogni piattaforma configurata. Per predisporre anche la configurazione di valutazione lato server di Langfuse (una connessione LLM per il modello giudice, un evaluator simulation_llm_as_judge e una regola di valutazione per ogni dataset di simulazione, visibili nella sezione Evaluations di Langfuse), esegui:

uv run python tests/setup_simulation_evals.py

Lo script è idempotente e può essere rieseguito senza rischi.