Handleiding voor onderzoekers

Voor wie deze handleiding is

AI-onderzoekers en ontwikkelaars die experimenten in Agent-Lab willen verkennen, reproduceren en uitbreiden. Als je Python schrijft, Jupyter gebruikt en denkt in termen van experimenten, agents en pipelines, voel je je hier meteen thuis. Kennis van LLM's, RAG en de basis van containers is handig, maar niet vereist.

Agent-Lab biedt herbruikbare componenten (agenttypen, tools, integraties) plus een verzameling Jupyter-notebooks met stapsgewijze voorbeelden, zodat je snel productief bent.

Snelstart — voer de voorbeelden uit

Vereisten: Python 3.12+, een werkende Jupyter-omgeving (JupyterLab of Notebook) en optioneel een lokale Docker-installatie voor end-to-end-integraties. Werkend in een clone van de repository:

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

Open notebooks/ en begin met 01_…; werk daarna de notebooks door die je interesseren.

Opmerkingen:

• Notebooks zijn grotendeels op zichzelf staand; de kop van elk notebook vermeldt de vereiste omgevingsvariabelen en externe services (API-sleutels, endpoints).
• De vereiste sleutels staan in .env — kopieer .env.example en vul het in (zie de Configuratiereferentie).
• Wil je vanuit je eigen project met Agent-Lab experimenteren in plaats van vanuit de repository, voer dan pip install btech-agent-lab uit en stel de app samen met create_app() — zie Het framework uitbreiden in de Handleiding voor ontwikkelaars.

Projectstructuur — een korte rondleiding

• notebooks/ — interactieve voorbeelden van agenttypen, evaluatie en integraties. Begin hier.
• agent_lab/ — het package van het framework:
  • app_factory.py — de composition root: create_app().
  • core/ — configuratiebronnen, DI-container, resolutie van extra_deps.
  • domain/ — modellen, repository-interfaces, exceptions (het Domeinmodel van entiteiten).
  • services/ — businesslogica en de implementaties in agent_types/.
  • interface/ — api/ (HTTP-routers) en mcp/ (de MCP-server).
  • infrastructure/ — adapters voor database, authenticatie, metrics/tracing.
• tests/ — de suites unit/, integration/, template/ en simulation/ (zie Testen & simulaties).
• doc/ — de documentatie die je nu leest.

Als je deze lagen begrijpt, weet je waar gedrag zit: voorbeelden in notebooks, kerncontracten in core/ en domain/, en adapters in infrastructure/.

Notebooks — de belangrijkste leerroute

Gebruikelijke volgorde:

Elk notebook bevat: een korte beschrijving van het doel van het experiment, de vereiste omgevingsvariabelen en secrets, hulpfuncties en geprinte/visuele uitvoer om beslissingen en metrics van de agent te inspecteren.

Tip: doorloop de notebooks op volgorde voor een geleidelijke leercurve. Gebruik kleinere datasets en steekproeven tijdens het itereren, zodat runs snel blijven.

Kernbegrippen

• Agent — een geregistreerde implementatie onder agent_lab/services/agent_types/ (@discoverable_agent). Het register resolvet deze lazy via de DI-container en injecteert de gedeclareerde extra_deps.
• Tools — afzonderlijke vaardigheden die een agent kan aanroepen (zoeken, browsen, TTS/ASR), geïmplementeerd als adapters in agent_lab/infrastructure/ of agent_lab/interface/.
• Container — het DI-compositieobject (agent_lab/core/container.py); maak er een subklasse van om providers voor je experimenten toe te voegen.
• Repositories — interfaces voor datatoegang in agent_lab/domain/repositories/.
• ConfigSource — waar de configuratie vandaan komt; gebruik de YAML-bronnen bij experimenten en Vault in productie.

Als je gedrag wilt aanpassen, bepaal dan of de wijziging experimenteel is (alleen notebook), architectureel (core/domain/services) of op integratieniveau (adapter in infrastructure). Geef de voorkeur aan kleine, testbare wijzigingen — en voeg een notebook toe of werk er een bij om het nieuwe gedrag te laten zien.

Experimenten uitvoeren en resultaten vastleggen

Notebooks printen tussenstappen; voor robuustere experimenten:

• Gebruik deterministische seeds waar willekeur ertoe doet.

• Leg de metrics vast die relevant zijn voor je vraag — latency, tokengebruik, aantal toolaanroepen, scores van de judge. De observability-laag exporteert alles als OpenTelemetry (zie Observability); het simulatieharness logt de scores van de judge naar Langfuse/LangWatch (zie Testen & simulaties).

• Exporteer voor herhaalbare runs notebookcellen naar scripts en voer ze uit in CI of op rekennodes:

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

• Het bestand docker/app/Dockerfile bouwt een runtime-image met vastgezette versies voor reproduceerbare uitvoering.

Nieuw gedrag prototypen

1. Een nieuw agenttype toevoegen: maak de klasse aan onder agent_lab/services/agent_types/, voorzie die van de decorator @discoverable_agent("your_type") en voeg een notebook toe dat de klasse via de DI-container mount en met een klein scenario test. De volledige walkthrough staat in Agentische workflows bouwen.
2. Een embeddingsprovider vervangen: implementeer een compatibele adapter onder agent_lab/infrastructure/ en valideer die met notebook 01.
3. Een retrieval-store of vectordatabase toevoegen: implementeer repository-methoden in agent_lab/domain/repositories/ en een adapter in agent_lab/infrastructure/database/; vul die met een klein loader-notebook en demonstreer retrieval in een query-notebook.

Ontwerptip: houd adapterinterfaces smal en test ze geïsoleerd met kleine unittests.

Testen en evalueren

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

Als je kerngedrag wijzigt, voeg dan een unittest toe en een kort notebook dat de wijziging demonstreert — die combinatie maakt onderzoek hier reproduceerbaar. Het volledige harness, de configuratie van de judge en de evaluatieplatforms worden behandeld in Testen & simulaties.

Checklist voor reproduceerbaarheid

• Zet je omgeving vast (uv + pyproject.toml / uv.lock).
• Leg seeds en configuratiebestanden vast (config-dev.yml, config-test.yml).
• Bewaar de notebook-checkpoint en eventuele uitvoerartefacten (CSV/JSON) bij je experiment.
• Noteer naar welke tracing-endpoints je hebt geëxporteerd — traces zijn het logboek van je experiment.