Guida per sviluppatori

Due modi di sviluppare

Agent-Lab è un framework che usi come libreria, ma è anche un repository in cui puoi lavorare direttamente. Entrambe le modalità sono supportate:

• Come libreria (consigliato per i prodotti). Aggiungi btech-agent-lab al tuo progetto, definisci gli agenti estendendo le classi base e assembla l'app con create_app(). Estendi il framework tramite la sua API pubblica (sottoclassi, decorator e configurazione) senza mai modificare il codice del framework. Inizia dal Tutorial o dal Quickstart, poi leggi Estendere il framework. Per evitare il codice boilerplate, genera un progetto consumatore già pronto con uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (vedi cookiecutter/README.md).
• Nel repository (per i contributori e l'implementazione di riferimento). Clona il repository e aggiungi gli agenti in agent_lab/services/agent_types/, esegui l'app di riferimento inclusa e usa i notebook e i test di integrazione. È così che vengono sviluppati gli agenti integrati. Vedi Creare workflow agentici.

Entrambi i percorsi usano gli stessi elementi costitutivi; l'unica differenza è dove risiede il tuo codice. Scegli quello più adatto al tuo progetto.

Configurazione iniziale

Installazione

Agent-Lab richiede Python 3.12+ e usa uv per la gestione delle dipendenze.

Usare Agent-Lab come libreria: installalo nel tuo progetto:

pip install btech-agent-lab
# or
uv add btech-agent-lab

Lavorare nel repository: clonalo e sincronizza l'ambiente:

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Assicurati che Docker o un altro container runtime sia installato e in esecuzione: i test di integrazione lo usano (tramite testcontainers) e i file Docker Compose inclusi forniscono le dipendenze dell'applicazione.

Copiare il file di ambiente di esempio

cp .env.example .env

Questo file contiene le API key dei fornitori di AI e gli endpoint usati dalle simulazioni di agenti. Ogni variabile è documentata nel Riferimento della configurazione.

Implementazione di riferimento

Il repository include un'applicazione di riferimento completa (agent_lab.main) che registra tutti gli agenti integrati: RAG, automazione del browser, memo vocali, visione e supervisor multi-agente. È sia un prodotto pronto per il deployment sia l'esempio canonico di come usare il framework: non è altro che una chiamata a create_app() sui package degli agenti integrati.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

Usala come riferimento concreto mentre crei la tua app e come modo più rapido per provare Agent-Lab end-to-end. Il provisioning della sua infrastruttura (i tre database PostgreSQL, Redis, Keycloak, Vault) in sviluppo o in produzione è descritto nella guida al deployment. La sezione seguente mostra come eseguirla in locale.

Eseguire l'applicazione

Avviare l'applicazione con Uvicorn

Per lo sviluppo e il debug con un IDE, esegui direttamente l'app di riferimento:

uvicorn agent_lab.main:app --reload

Accedi alla documentazione OpenAPI interattiva su http://localhost:8000/docs.

Quando usi Agent-Lab come libreria, esegui la tua app nello stesso modo: punta uvicorn al modulo che chiama create_app():

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Avviare l'applicazione con Docker Compose

Due file Docker Compose preconfigurati eseguono l'app di riferimento insieme a uno stack di osservabilità:

• compose-grafana.yml: l'applicazione più Grafana, Prometheus, Tempo e Loki.
• compose-opensearch.yml: l'applicazione più OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

Dopo l'avvio dell'applicazione, l'API è disponibile su http://localhost:18000/docs. Dashboard di osservabilità:

• Grafana: http://localhost:3000 (credenziali predefinite: admin/admin). Vedi l'esempio con Grafana.
• OpenSearch Dashboards: http://localhost:5601. Vedi l'esempio con OpenSearch.

Pratiche di sviluppo

Dependency injection

L'applicazione usa Dependency Injector per la dependency injection, che mantiene separate le responsabilità e semplifica i test.

Il container è definito in agent_lab/core/container.py. Quando usi Agent-Lab come libreria, crea una sottoclasse di Container per aggiungere i tuoi provider e passa l'istanza a create_app(container=...). Quando lavori nel repository, registra i servizi aggiuntivi del framework direttamente nel container.

Configurazione dell'applicazione

La configurazione viene caricata tramite una ConfigSource (vedi agent_lab/core/config.py) e collegata al container DI. Il framework include tre sorgenti YAML per sviluppo e test, selezionate automaticamente tramite variabile d'ambiente:

• config-dev.yml: ambiente di sviluppo, attivato quando DEVELOPING è impostata; pensato per il debug nell'IDE.
• config-test.yml: ambiente di test, attivato quando TESTING è impostata; usato dalla configurazione dei test di integrazione.
• config-docker.yml: ambiente Docker Compose, attivato quando DOCKER è impostata.

Questi file definiscono impostazioni come le connessioni ai database e l'autenticazione, e sono destinati solo a sviluppo e test. In produzione, usa Vault tramite VaultConfigSource (l'impostazione predefinita quando non è impostato alcun flag d'ambiente). Per fornire la configurazione da un backend diverso, implementa una tua ConfigSource e passala a create_app(config_source=...). Ogni chiave di configurazione e variabile d'ambiente è documentata nel Riferimento della configurazione.

Modello di dominio delle entità

Consulta il Modello di dominio delle entità per il modello dei dati: le entità e le loro relazioni usate in tutta l'applicazione.

Logging e osservabilità

L'applicazione usa OpenTelemetry per logging e osservabilità; la configurazione si trova in agent_lab/infrastructure/metrics/tracer.py. Le chiamate FastAPI, HTTPX, LangChain, SQLAlchemy e OpenAI sono strumentate di serie, con backend pluggable per Langfuse e LangWatch. Consulta la guida all'osservabilità per i dettagli.

Test

Il progetto usa pytest con un'attenzione particolare ai test di integrazione (soglia di copertura: 90%), supportati da Testcontainers, così i test vengono eseguiti su servizi reali in container Docker. Una suite di simulazione separata valuta il comportamento degli agenti end-to-end con un LLM-as-judge.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

La prima esecuzione può richiedere diversi minuti, perché scarica le immagini Docker e i modelli di embedding. Consulta la guida ai test per il quadro completo.

Inizializzare pre-commit

Se intendi contribuire al codice o creare nuovi agenti basati su Agent-Lab, installa gli hook di pre-commit:

pre-commit install

In questo modo il tuo codice rispetta gli standard di codifica del progetto prima di ogni commit.

Creare workflow agentici

Agent-Lab è basato su LangGraph, che offre un modo potente per creare workflow agentici usando gli LLM. Crearne uno è un processo semplice grazie all'architettura modulare e alle classi base degli agenti.

Definire una nuova implementazione di agente

L'agente è un concetto fondamentale in Agent-Lab: rappresenta un'entità autonoma in grado di eseguire task, prendere decisioni e interagire con altri agenti o sistemi esterni. Un agente è un'implementazione concreta di una delle classi base:

Una classe che estende WorkflowAgentBase definisce:

• un workflow che rappresenta il comportamento dell'agente: task, processi decisionali e interazioni con altri agenti o sistemi esterni.
• parametri di inizializzazione come i prompt (template Jinja2) e altre impostazioni che personalizzano il comportamento dell'agente (collection del vector store, temperatura e così via).

Ecco un esempio di parametri di inizializzazione persistiti per un agente che esegue trascrizione e analisi vocale, dopo che l'agente è stato creato e salvato nel database:

È possibile creare e perfezionare tramite la REST API più agenti basati sulla stessa implementazione.

Registrare l'agente con @discoverable_agent

Applica alla tua sottoclasse di AgentBase il decorator @discoverable_agent("<agent_type>"). Quel solo decorator è tutta la registrazione di cui un agente ha bisogno: rende l'agente

• individuabile dal registro degli agenti (agent_lab/services/agent_types/registry.py),
• risolvibile tramite il container DI, che lo istanzia in modo lazy e inietta le eventuali extra_deps dichiarate,
• valido per l'API, perché lo schema di creazione degli agenti valida agent_type rispetto al registro in modo dinamico.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

Nota (migrazione): le versioni precedenti richiedevano di collegare manualmente ogni agente in container.py, di aggiungerlo a registry.py e di estendere lo schema Pydantic in agents/schema.py. Questi passaggi sono obsoleti: @discoverable_agent li gestisce tutti. Le extra_deps che dichiari vengono risolte per nome sul container (eventualmente una sua sottoclasse) al momento dell'istanziazione.

Se un agente ha bisogno di collaboratori oltre ad AgentUtils, esponili come provider sul container (crea una sottoclasse di Container quando usi la libreria) e indicali in extra_deps.

Rendere l'agente individuabile

Il framework importa solo i moduli di agenti che gli vengono indicati, così che il decorator venga eseguito:

• Nel repository: posiziona l'agente in agent_lab/services/agent_types/: l'app di riferimento analizza quel package come parte di DEFAULT_SCAN_PACKAGES (create_app()).

• Come libreria: passa il tuo package a create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) (un elenco esplicito sostituisce quello predefinito, ed è anche il modo per escludere le funzionalità integrate) oppure pubblicalo da un package installato tramite il gruppo di entry point agent_lab.agents, così che i consumatori lo rilevino automaticamente:

  # pyproject.toml of the package that ships the agents
  [project.entry-points."agent_lab.agents"]
  my_agents = "my_agents"

Sperimentare con l'implementazione dell'agente

Consulta i notebook per esempi di test interattivi di un agente con Jupyter, usando lo stesso meccanismo di dependency injection. È un modo comodo per prototipare e validare il comportamento in un ambiente controllato: vedi la Guida per ricercatori.

Interfaccia REST API dell'agente

Una volta registrato un agente, crea e gestisci le sue istanze tramite la REST API: puoi eseguire diverse istanze configurate della stessa implementazione, ognuna con i propri prompt e impostazioni. Consulta il Riferimento della REST API per il catalogo degli endpoint e gli esempi di richiesta.

Testare l'agente

• I test di integrazione (tests/integration/) validano l'agente su infrastruttura reale con pytest e testcontainers.
• Le simulazioni (tests/simulation/) valutano il comportamento end-to-end con un LLM-as-judge. Consulta la guida ai test.

Server MCP

Consulta la guida al server MCP per esporre i tuoi agenti (e tool aggiuntivi) a client MCP come Claude Desktop per la discovery degli agenti, la cronologia dei dialoghi e la comunicazione tra agenti.

Estendere il framework

Quando usi Agent-Lab come libreria, definisci l'applicazione interamente tramite create_app() e l'API pubblica esportata dal package di primo livello agent_lab, senza mai modificare il codice del framework:

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

Tutto quanto sopra è esportato da agent_lab (vedi agent_lab/__init__.py); l'elenco completo delle chiavi di configurazione usate da queste opzioni si trova nel Riferimento della configurazione.

Contribuire

Il supporto della community è molto apprezzato. Se riscontri problemi o hai suggerimenti di miglioramento, segnalali creando una issue nella nostra pagina GitHub Issues.

Per contribuire al progetto, segui questi passaggi:

1. Crea un fork del repository.
2. Crea un nuovo branch per la tua funzionalità o correzione.
3. Attiva gli hook di pre-commit eseguendo pre-commit install, apporta le tue modifiche ed esegui il commit con messaggi chiari e concisi.
4. Assicurati che le tue modifiche superino gli hook di pre-commit e la soglia di copertura del 90% (make test).
5. Esegui il push delle modifiche nel tuo fork del repository.
6. Crea una Pull Request (PR) verso il branch main del repository originale.

Esamineremo la tua PR e ti daremo un riscontro. Grazie per i tuoi contributi e il tuo supporto!

Deployment in produzione

Consulta la guida al deployment per eseguire il deployment dell'applicazione di riferimento in produzione usando i chart Helm e gli script Terraform inclusi.