Handleiding voor ontwikkelaars

Twee manieren van ontwikkelen

Agent-Lab is een framework dat je als bibliotheek gebruikt, en het is ook een repository waarin je rechtstreeks kunt werken. Beide worden ondersteund:

• Als bibliotheek (aanbevolen voor producten). Voeg btech-agent-lab toe aan je eigen project, definieer agents door de basisklassen uit te breiden en stel de app samen met create_app(). Je breidt het framework uit via de publieke API — subklassen, decorators en configuratie — en past nooit code van het framework aan. Begin met de Tutorial of de Snelstart en lees daarna Het framework uitbreiden. Wil je de boilerplate overslaan, scaffold dan een kant-en-klaar consumerproject met uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (zie cookiecutter/README.md).
• In de repository (voor bijdragers en de referentie-implementatie). Clone de repository en voeg agents toe onder agent_lab/services/agent_types/, voer de meegeleverde referentie-app uit en gebruik de notebooks en integratietests. Zo worden de ingebouwde agents ontwikkeld. Zie Agentische workflows bouwen.

Beide routes gebruiken dezelfde bouwstenen; het verschil zit alleen in waar je code staat. Kies wat bij je project past.

Installatie

Installeren

Agent-Lab is gericht op Python 3.12+ en gebruikt uv voor het beheer van afhankelijkheden.

Agent-Lab als bibliotheek gebruiken — installeer het in je eigen project:

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

Werken in de repository — clone die en synchroniseer de omgeving:

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

Zorg dat Docker of een andere container-runtime is geïnstalleerd en draait — de integratietests gebruiken die (via testcontainers) en de meegeleverde Docker Compose-bestanden leveren de afhankelijkheden van de applicatie.

Het voorbeeldbestand voor de omgeving kopiëren

cp .env.example .env

Dit bestand bevat API-sleutels voor AI-leveranciers en de endpoints die worden gebruikt door de agentsimulaties. Elke variabele is gedocumenteerd in de Configuratiereferentie.

Referentie-implementatie

De repository bevat een complete referentieapplicatie (agent_lab.main) die alle ingebouwde agents registreert — RAG, browserautomatisering, voice memos, vision en multi-agent-supervisors. Het is zowel een deploybaar product als het canonieke voorbeeld van hoe je het framework gebruikt: het is niets meer dan een aanroep van create_app() over de ingebouwde agentpackages.

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

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

Gebruik het als levende referentie terwijl je je eigen app bouwt, en als snelste manier om Agent-Lab end-to-end uit te proberen. Het inrichten van de infrastructuur (de drie PostgreSQL-databases, Redis, Keycloak, Vault) voor ontwikkeling of productie wordt behandeld in de Deploymenthandleiding. De volgende sectie laat zien hoe je het lokaal uitvoert.

De applicatie uitvoeren

De applicatie starten met Uvicorn

Voer voor ontwikkeling en debuggen in een IDE de referentie-app rechtstreeks uit:

uvicorn agent_lab.main:app --reload

De interactieve OpenAPI-documentatie vind je op http://localhost:8000/docs.

Als je Agent-Lab als bibliotheek gebruikt, voer je je eigen app op dezelfde manier uit — laat uvicorn wijzen naar de module die create_app() aanroept:

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

De applicatie starten met Docker Compose

Twee vooraf geconfigureerde Docker Compose-bestanden draaien de referentie-app samen met een observability-stack:

• compose-grafana.yml: de applicatie plus Grafana, Prometheus, Tempo en Loki.
• compose-opensearch.yml: de applicatie plus OpenSearch Dashboards.

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

Nadat de applicatie is gestart, is de API beschikbaar op http://localhost:18000/docs. Observability-dashboards:

• Grafana: http://localhost:3000 (standaardinloggegevens: admin/admin). Zie het Grafana-voorbeeld.
• OpenSearch Dashboards: http://localhost:5601. Zie het OpenSearch-voorbeeld.

Ontwikkelpraktijken

Dependency injection

De applicatie gebruikt Dependency Injector voor dependency injection, wat verantwoordelijkheden gescheiden houdt en testen eenvoudiger maakt.

De container is gedefinieerd in agent_lab/core/container.py. Als je Agent-Lab als bibliotheek gebruikt, maak dan een subklasse van Container om je eigen providers toe te voegen en geef de instantie door aan create_app(container=...). Als je in de repository werkt, registreer je extra frameworkservices rechtstreeks op de container.

Applicatieconfiguratie

De configuratie wordt geladen via een ConfigSource (zie agent_lab/core/config.py) en aan de DI-container gekoppeld. Het framework bevat drie YAML-bronnen voor ontwikkeling en testen, die automatisch worden gekozen op basis van een omgevingsvariabele:

• config-dev.yml: ontwikkelomgeving, geactiveerd als DEVELOPING is ingesteld — bedoeld voor debuggen in de IDE.
• config-test.yml: testomgeving, geactiveerd als TESTING is ingesteld — gebruikt door de setup van de integratietests.
• config-docker.yml: Docker Compose-omgeving, geactiveerd als DOCKER is ingesteld.

Deze bestanden definiëren instellingen zoals databaseverbindingen en authenticatie, en zijn alleen bedoeld voor ontwikkeling en testen. Gebruik in productie Vault via VaultConfigSource (de standaard als er geen omgevingsvlag is ingesteld). Om configuratie uit een andere backend te leveren, implementeer je je eigen ConfigSource en geef je die door aan create_app(config_source=...). Elke configuratiesleutel en omgevingsvariabele is gedocumenteerd in de Configuratiereferentie.

Domeinmodel van entiteiten

Zie het Domeinmodel van entiteiten voor het datamodel — de entiteiten en hun relaties die in de hele applicatie worden gebruikt.

Logging en observability

De applicatie gebruikt OpenTelemetry voor logging en observability; de setup staat in agent_lab/infrastructure/metrics/tracer.py. Aanroepen van FastAPI, HTTPX, LangChain, SQLAlchemy en OpenAI worden standaard geïnstrumenteerd, met inplugbare backends voor Langfuse en LangWatch. Zie de handleiding Observability voor details.

Testen

Het project gebruikt pytest met de nadruk op integratietests (coverage-drempel: 90%), ondersteund door Testcontainers, zodat tests draaien tegen echte services in Docker-containers. Een aparte simulatiesuite evalueert het gedrag van agents end-to-end met een LLM-as-judge.

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

De eerste uitvoering kan enkele minuten duren, omdat Docker-images en embeddingmodellen worden gedownload. Zie de testhandleiding voor het volledige beeld.

Pre-commit initialiseren

Als je van plan bent bij te dragen aan de codebase of nieuwe agents te bouwen op Agent-Lab, installeer dan de pre-commit-hooks:

pre-commit install

Zo weet je zeker dat je code voldoet aan de codeerstandaarden van het project voordat je commit.

Agentische workflows bouwen

Agent-Lab is gebouwd op LangGraph, dat een krachtige manier biedt om agentische workflows met LLM's te bouwen. Er een bouwen is eenvoudig, dankzij de modulaire architectuur en de basisklassen voor agents.

Een nieuwe agentimplementatie definiëren

Agent is een kernbegrip in Agent-Lab: een autonome entiteit die taken kan uitvoeren, beslissingen kan nemen en kan communiceren met andere agents of externe systemen. Een agent is een concrete implementatie van een van de basisklassen:

Een klasse die WorkflowAgentBase uitbreidt, definieert:

• een workflow die het gedrag van de agent weergeeft — taken, besluitvorming en interacties met andere agents of externe systemen.
• initialisatieparameters zoals de prompts (Jinja2-templates) en andere instellingen die het gedrag van de agent aanpassen (vector store-collecties, temperature, enzovoort).

Hier is een voorbeeld van opgeslagen initialisatieparameters voor een agent die spraak transcribeert en analyseert, nadat de agent is aangemaakt en in de database is opgeslagen:

Via de REST API kun je meerdere agents met dezelfde implementatie aanmaken en verfijnen.

De agent registreren met @discoverable_agent

Voorzie je subklasse van AgentBase van @discoverable_agent("<agent_type>"). Die ene decorator is alle registratie die een agent nodig heeft — hij maakt de agent:

• vindbaar voor het agentregister (agent_lab/services/agent_types/registry.py),
• resolvebaar via de DI-container, die de agent lazy instantieert en eventuele gedeclareerde extra_deps injecteert,
• geldig in de API, omdat het schema voor het aanmaken van agents agent_type dynamisch valideert tegen het register.

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
    ...

Opmerking (migratie): in eerdere versies moest je elke agent handmatig koppelen in container.py, toevoegen aan registry.py en het Pydantic-schema uitbreiden in agents/schema.py. Die stappen zijn verouderd — @discoverable_agent regelt ze allemaal. Alle extra_deps die je declareert, worden bij het instantiëren op naam opgezocht in de (mogelijk gesubklasste) container.

Als een agent naast AgentUtils nog andere collaborators nodig heeft, stel die dan beschikbaar als providers op de container (maak een subklasse van Container als je de bibliotheek gebruikt) en noem ze in extra_deps.

De agent vindbaar maken

Het framework importeert alleen agentmodules waarvan het op de hoogte is gesteld, zodat de decorator wordt uitgevoerd:

• In de repository: plaats de agent onder agent_lab/services/agent_types/ — de referentie-app scant dat package als onderdeel van DEFAULT_SCAN_PACKAGES (create_app()).

• Als bibliotheek: geef je package door aan create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — een expliciete lijst vervangt de standaardwaarden (zo sluit je ook ingebouwde functionaliteit uit) — of publiceer het vanuit een geïnstalleerd package via de entry-pointgroep agent_lab.agents, zodat consumers het automatisch oppikken:

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

Experimenteren met de agentimplementatie

Zie de notebooks voor voorbeelden van het interactief testen van een agent met Jupyter, met hetzelfde mechanisme voor dependency injection. Dit is een handige manier om gedrag te prototypen en te valideren in een gecontroleerde omgeving — zie de Handleiding voor onderzoekers.

REST API-interface voor agents

Zodra een agent is geregistreerd, maak en beheer je instanties ervan via de REST API — je kunt meerdere geconfigureerde instanties van dezelfde implementatie draaien, elk met eigen prompts en instellingen. Zie de REST API-referentie voor de endpointcatalogus en voorbeeldrequests.

De agent testen

• Integratietests (tests/integration/) valideren de agent tegen echte infrastructuur met pytest en testcontainers.
• Simulaties (tests/simulation/) evalueren het gedrag end-to-end met een LLM-as-judge. Zie de testhandleiding.

MCP-server

Zie de Handleiding MCP-server voor het beschikbaar stellen van je agents (en extra tools) aan MCP-clients zoals Claude Desktop, voor het ontdekken van agents, gespreksgeschiedenis en communicatie van agent tot agent.

Het framework uitbreiden

Als je Agent-Lab als bibliotheek gebruikt, vorm je de applicatie volledig via create_app() en de publieke API die wordt geëxporteerd vanuit het top-level package agent_lab — nooit door code van het framework aan te passen:

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."],
)

Alles hierboven wordt geëxporteerd vanuit agent_lab (zie agent_lab/__init__.py); de volledige lijst met configuratiesleutels die deze opties gebruiken, staat in de Configuratiereferentie.

Bijdragen

Steun vanuit de community wordt zeer gewaardeerd. Loop je tegen problemen aan of heb je suggesties voor verbeteringen, meld die dan door een issue aan te maken op onze pagina GitHub Issues.

Volg deze stappen om bij te dragen aan het project:

1. Fork de repository.
2. Maak een nieuwe branch aan voor je feature of bugfix.
3. Activeer de pre-commit-hooks door pre-commit install uit te voeren, breng je wijzigingen aan en commit ze met duidelijke en beknopte berichten.
4. Zorg dat je wijzigingen slagen voor de pre-commit-hooks en de coverage-drempel van 90% (make test).
5. Push je wijzigingen naar je fork van de repository.
6. Maak een Pull Request (PR) aan naar de main-branch van de oorspronkelijke repository.

We beoordelen je PR en geven feedback. Bedankt voor je bijdragen en steun!

Deployment in productie

Zie de Deploymenthandleiding voor het deployen van de referentieapplicatie in productie met de meegeleverde Helm-charts en Terraform-scripts.