Guide du chercheur

À qui s'adresse ce guide

Aux chercheurs en IA et aux développeurs qui souhaitent explorer, reproduire et étendre des expériences dans Agent-Lab. Si vous écrivez du Python, utilisez Jupyter et raisonnez en termes d'expériences, d'agents et de pipelines, vous vous sentirez chez vous. Une connaissance des LLM, du RAG et des bases des conteneurs est utile, mais pas indispensable.

Agent-Lab fournit des composants réutilisables (types d'agents, outils, intégrations) ainsi qu'une collection de notebooks Jupyter contenant des exemples pas à pas, pour vous permettre d'être rapidement productif.

Démarrage rapide — exécuter les exemples

Prérequis : Python 3.12+, un environnement Jupyter fonctionnel (JupyterLab ou Notebook) et, en option, Docker en local pour les intégrations de bout en bout. En travaillant dans un clone du dépôt :

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

Ouvrez notebooks/ et commencez par 01_…, puis poursuivez avec ceux qui vous intéressent.

Remarques :

• Les notebooks sont pour la plupart autonomes ; l'en-tête de chacun indique les variables d'environnement et les services externes requis (clés d'API, points de terminaison).
• Les clés requises se trouvent dans .env — copiez .env.example et complétez-le (voir la Référence de configuration).
• Pour expérimenter avec Agent-Lab depuis votre propre projet plutôt que depuis le dépôt, exécutez pip install btech-agent-lab et assemblez l'application avec create_app() — voir Étendre le framework dans le Guide du développeur.

Organisation du projet — visite rapide

• notebooks/ — exemples interactifs de types d'agents, d'évaluation et d'intégrations. Commencez ici.
• agent_lab/ — le package du framework :
  • app_factory.py — la racine de composition : create_app().
  • core/ — sources de configuration, conteneur DI, résolution des extra_deps.
  • domain/ — modèles, interfaces de repositories, exceptions (le Modèle de domaine des entités).
  • services/ — logique métier et implémentations agent_types/.
  • interface/ — api/ (routeurs HTTP) et mcp/ (le serveur MCP).
  • infrastructure/ — adaptateurs de base de données, d'authentification et de métriques/traçage.
• tests/ — suites unit/, integration/, template/ et simulation/ (voir Tests et simulations).
• doc/ — la documentation que vous êtes en train de lire.

Comprendre ces couches vous indique où réside chaque comportement : les exemples dans notebooks, les contrats fondamentaux dans core/ et domain/, et les adaptateurs dans infrastructure/.

Notebooks — le principal parcours d'apprentissage

Progression type :

Chaque notebook contient : une brève description de l'objectif de l'expérience, les variables d'environnement et secrets requis, des fonctions utilitaires, ainsi que des sorties textuelles ou visuelles pour examiner les décisions et les métriques de l'agent.

Astuce : exécutez les notebooks dans l'ordre pour une courbe d'apprentissage progressive. Utilisez des jeux de données et des échantillons plus petits pendant les itérations afin que les exécutions restent rapides.

Concepts clés

• Agent — une implémentation enregistrée sous agent_lab/services/agent_types/ (@discoverable_agent). Le registre la résout de manière paresseuse via le conteneur DI, en injectant les extra_deps déclarées.
• Outils — des capacités distinctes qu'un agent peut appeler (recherche, navigation, TTS/ASR), implémentées sous forme d'adaptateurs dans agent_lab/infrastructure/ ou agent_lab/interface/.
• Container — l'objet de composition DI (agent_lab/core/container.py) ; créez-en une sous-classe pour ajouter des providers pour vos expériences.
• Repositories — les interfaces d'accès aux données dans agent_lab/domain/repositories/.
• ConfigSource — l'origine de la configuration ; utilisez les sources YAML pour les expériences, et Vault en production.

Lorsque vous souhaitez modifier un comportement, déterminez si la modification est expérimentale (notebook uniquement), architecturale (core/domain/services) ou au niveau de l'intégration (adaptateur dans infrastructure). Privilégiez des modifications petites et testables — et ajoutez ou mettez à jour un notebook pour illustrer le nouveau comportement.

Mener des expériences et recueillir les résultats

Les notebooks affichent les étapes intermédiaires ; pour des expériences plus robustes :

• Utilisez des graines déterministes lorsque l'aléatoire entre en jeu.

• Recueillez les métriques pertinentes pour votre question — latence, consommation de jetons, nombre d'appels d'outils, scores du juge. La couche d'observabilité exporte l'ensemble au format OpenTelemetry (voir Observabilité) ; le banc de simulation consigne les scores du juge dans Langfuse/LangWatch (voir Tests et simulations).

• Pour des exécutions reproductibles, exportez les cellules des notebooks sous forme de scripts et exécutez-les en CI ou sur des nœuds de calcul :

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

• Le fichier docker/app/Dockerfile construit une image d'exécution aux versions figées pour une exécution reproductible.

Prototyper de nouveaux comportements

1. Ajouter un nouveau type d'agent : créez la classe sous agent_lab/services/agent_types/, décorez-la avec @discoverable_agent("your_type"), puis ajoutez un notebook qui la monte via le conteneur DI et la met à l'épreuve sur un petit scénario. La présentation complète se trouve dans Créer des workflows agentiques.
2. Remplacer un fournisseur d'embeddings : implémentez un adaptateur compatible sous agent_lab/infrastructure/ et validez-le avec le notebook 01.
3. Ajouter un stockage de récupération ou une base vectorielle : implémentez les méthodes de repository dans agent_lab/domain/repositories/ et un adaptateur dans agent_lab/infrastructure/database/ ; alimentez-le avec un petit notebook de chargement et démontrez la récupération dans un notebook de requêtes.

Conseil de conception : gardez des interfaces d'adaptateurs restreintes et testez-les isolément à l'aide de petits tests unitaires.

Tests et évaluation

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

Lorsque vous modifiez un comportement fondamental, ajoutez un test unitaire et un court notebook illustrant la modification — c'est cette association qui rend la recherche reproductible ici. Le banc d'essai complet, la configuration du juge et les plateformes d'évaluation sont traités dans Tests et simulations.

Liste de contrôle de la reproductibilité

• Figez votre environnement (uv + pyproject.toml / uv.lock).
• Consignez les graines et les fichiers de configuration (config-dev.yml, config-test.yml).
• Enregistrez le checkpoint du notebook et tous les artefacts de sortie (CSV/JSON) avec votre expérience.
• Notez les points de terminaison de traçage vers lesquels vous avez exporté — les traces constituent le journal de votre expérience.