Guida per ricercatori

A chi è rivolta questa guida

A ricercatori di AI e sviluppatori che vogliono esplorare, riprodurre ed estendere esperimenti in Agent-Lab. Se scrivi in Python, usi Jupyter e ragioni in termini di esperimenti, agenti e pipeline, ti sentirai a casa. Avere familiarità con LLM, RAG e le basi dei container è utile, ma non obbligatorio.

Agent-Lab fornisce componenti riutilizzabili (tipi di agente, tool, integrazioni) più una raccolta di notebook Jupyter con esempi passo passo, così puoi diventare produttivo rapidamente.

Avvio rapido: esegui gli esempi

Requisiti: Python 3.12+, un ambiente Jupyter funzionante (JupyterLab o Notebook) e, facoltativamente, Docker in locale per le integrazioni end-to-end. Lavorando in un clone del repository:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

Apri notebooks/ e inizia da 01_…, proseguendo con quelli che ti interessano.

Note:

• I notebook sono per lo più autonomi; l'intestazione di ciascuno indica le variabili d'ambiente e i servizi esterni richiesti (API key, endpoint).
• Le chiavi richieste si trovano in .env: copia .env.example e compilalo (vedi il Riferimento della configurazione).
• Per sperimentare con Agent-Lab dal tuo progetto anziché dal repository, esegui pip install btech-agent-lab e assembla l'app con create_app(): vedi Estendere il framework nella Guida per sviluppatori.

Struttura del progetto: panoramica rapida

• notebooks/: esempi interattivi di tipi di agente, valutazione e integrazioni. Inizia da qui.
• agent_lab/: il package del framework:
  • app_factory.py: la composition root, create_app().
  • core/: sorgenti di configurazione, container DI, risoluzione di extra_deps.
  • domain/: modelli, interfacce dei repository, eccezioni (il Modello di dominio delle entità).
  • services/: logica di business e le implementazioni in agent_types/.
  • interface/: api/ (router HTTP) e mcp/ (il server MCP).
  • infrastructure/: adapter per database, autenticazione, metriche/tracing.
• tests/: le suite unit/, integration/, template/ e simulation/ (vedi Test e simulazioni).
• doc/: la documentazione che stai leggendo.

Comprendere questi livelli ti dice dove risiede il comportamento: gli esempi in notebooks, i contratti fondamentali in core/ e domain/ e gli adapter in infrastructure/.

Notebook: il percorso di apprendimento principale

Progressione tipica:

Ogni notebook contiene: una breve descrizione dell'obiettivo dell'esperimento, le variabili d'ambiente e i segreti richiesti, funzioni di supporto e output stampati o visuali per esaminare le decisioni e le metriche dell'agente.

Suggerimento: esegui i notebook in ordine per una curva di apprendimento graduale. Usa dataset e campioni più piccoli durante le iterazioni per mantenere le esecuzioni rapide.

Concetti fondamentali

• Agent: un'implementazione registrata in agent_lab/services/agent_types/ (@discoverable_agent). Il registro la risolve in modo lazy tramite il container DI, iniettando le extra_deps dichiarate.
• Tool: capacità specifiche che un agente può invocare (ricerca, navigazione, TTS/ASR), implementate come adapter in agent_lab/infrastructure/ o agent_lab/interface/.
• Container: l'oggetto di composizione DI (agent_lab/core/container.py); crea una sottoclasse per aggiungere provider per i tuoi esperimenti.
• Repository: interfacce di accesso ai dati in agent_lab/domain/repositories/.
• ConfigSource: da dove proviene la configurazione; usa le sorgenti YAML negli esperimenti e Vault in produzione.

Quando vuoi modificare un comportamento, stabilisci se la modifica è: sperimentale (solo nel notebook), architetturale (core/domain/services) o a livello di integrazione (adapter in infrastructure). Preferisci modifiche piccole e testabili, e aggiungi o aggiorna un notebook per mostrare il nuovo comportamento.

Eseguire esperimenti e registrare i risultati

I notebook stampano i passaggi intermedi; per esperimenti più solidi:

• Usa seed deterministici dove la casualità è rilevante.

• Registra le metriche pertinenti alla tua domanda: latenza, utilizzo dei token, numero di chiamate ai tool, punteggi del giudice. Il livello di osservabilità esporta tutto come OpenTelemetry (vedi Osservabilità); l'harness di simulazione registra i punteggi del giudice in Langfuse/LangWatch (vedi Test e simulazioni).

• Per esecuzioni ripetibili, esporta le celle dei notebook in script ed eseguili in CI o su nodi di calcolo:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• Il docker/app/Dockerfile crea un'immagine di runtime con versioni bloccate per un'esecuzione riproducibile.

Prototipare nuovi comportamenti

1. Aggiungere un nuovo tipo di agente: crea la classe in agent_lab/services/agent_types/, applica il decorator @discoverable_agent("your_type") e aggiungi un notebook che la monti tramite il container DI e la metta alla prova con un piccolo scenario. La procedura completa è in Creare workflow agentici.
2. Sostituire un provider di embedding: implementa un adapter compatibile in agent_lab/infrastructure/ e validalo con il notebook 01.
3. Aggiungere uno store di retrieval o un database vettoriale: implementa i metodi del repository in agent_lab/domain/repositories/ e un adapter in agent_lab/infrastructure/database/; popolalo con un piccolo notebook di caricamento e dimostra il retrieval in un notebook di query.

Suggerimento di design: mantieni ristrette le interfacce degli adapter e testale in isolamento con piccoli unit test.

Test e valutazione

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

Quando modifichi un comportamento fondamentale, aggiungi uno unit test e un breve notebook che dimostri la modifica: è questa combinazione a rendere la ricerca riproducibile. L'harness completo, la configurazione del giudice e le piattaforme di valutazione sono descritti in Test e simulazioni.

Checklist per la riproducibilità

• Blocca le versioni del tuo ambiente (uv + pyproject.toml / uv.lock).
• Registra i seed e i file di configurazione (config-dev.yml, config-test.yml).
• Salva il checkpoint del notebook e gli eventuali artefatti di output (CSV/JSON) insieme al tuo esperimento.
• Annota gli endpoint di tracing verso cui hai esportato i dati: le trace sono il registro del tuo esperimento.