Guide du développeur

Deux façons de développer

Agent-Lab est un framework que vous utilisez comme une bibliothèque, mais aussi un dépôt dans lequel vous pouvez travailler directement. Les deux approches sont prises en charge :

• Comme bibliothèque (recommandé pour les produits). Ajoutez btech-agent-lab à votre propre projet, définissez des agents en étendant les classes de base et assemblez l'application avec create_app(). Vous étendez le framework via son API publique — héritage, décorateurs et configuration — sans jamais modifier le code du framework. Commencez par le Tutoriel ou le Démarrage rapide, puis lisez Étendre le framework. Pour vous épargner le code passe-partout, générez un projet consommateur prêt à l'emploi avec uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (voir cookiecutter/README.md).
• Dans le dépôt (pour les contributeurs et l'implémentation de référence). Clonez le dépôt et ajoutez des agents sous agent_lab/services/agent_types/, exécutez l'application de référence fournie et utilisez les notebooks et les tests d'intégration. C'est ainsi que les agents intégrés sont développés. Voir Créer des workflows agentiques.

Les deux approches utilisent les mêmes briques ; la seule différence est l'endroit où votre code réside. Choisissez celle qui convient à votre projet.

Installation

Installer

Agent-Lab cible Python 3.12+ et utilise uv pour la gestion des dépendances.

Utiliser Agent-Lab comme bibliothèque — installez-le dans votre propre projet :

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

Travailler dans le dépôt — clonez-le et synchronisez l'environnement :

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

Assurez-vous que Docker ou un autre runtime de conteneurs est installé et en cours d'exécution — les tests d'intégration l'utilisent (via testcontainers) et les fichiers Docker Compose fournis lancent les dépendances de l'application.

Copier le fichier d'environnement d'exemple

cp .env.example .env

Ce fichier contient les clés d'API des fournisseurs d'IA et les points de terminaison utilisés par les simulations d'agents. Chaque variable est documentée dans la Référence de configuration.

Implémentation de référence

Le dépôt fournit une application de référence complète (agent_lab.main) qui enregistre tous les agents intégrés — RAG, automatisation de navigateur, mémos vocaux, vision et superviseurs multi-agents. C'est à la fois un produit déployable et l'exemple canonique d'utilisation du framework : il ne s'agit de rien d'autre qu'un appel à create_app() sur les packages d'agents intégrés.

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

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

Servez-vous-en comme d'une référence vivante pendant que vous construisez votre propre application, et comme du moyen le plus rapide d'essayer Agent-Lab de bout en bout. Le provisionnement de son infrastructure (les trois bases de données PostgreSQL, Redis, Keycloak, Vault) en développement comme en production est décrit dans le guide de déploiement. La section suivante montre comment l'exécuter en local.

Exécuter l'application

Démarrer l'application avec Uvicorn

Pour le développement et le débogage dans un IDE, exécutez directement l'application de référence :

uvicorn agent_lab.main:app --reload

Accédez à la documentation OpenAPI interactive à l'adresse http://localhost:8000/docs.

Lorsque vous utilisez Agent-Lab comme bibliothèque, vous exécutez votre application de la même manière — pointez uvicorn vers le module qui appelle create_app() :

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

Démarrer l'application avec Docker Compose

Deux fichiers Docker Compose préconfigurés exécutent l'application de référence avec une stack d'observabilité :

• compose-grafana.yml : l'application plus Grafana, Prometheus, Tempo et Loki.
• compose-opensearch.yml : l'application plus OpenSearch Dashboards.

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

Une fois l'application démarrée, l'API est disponible à l'adresse http://localhost:18000/docs. Tableaux de bord d'observabilité :

• Grafana : http://localhost:3000 (identifiants par défaut : admin/admin). Voir l'exemple avec Grafana.
• OpenSearch Dashboards : http://localhost:5601. Voir l'exemple avec OpenSearch.

Pratiques de développement

Injection de dépendances

L'application utilise Dependency Injector pour l'injection de dépendances, ce qui permet de bien séparer les responsabilités et facilite les tests.

Le conteneur est défini dans agent_lab/core/container.py. Lorsque vous utilisez Agent-Lab comme bibliothèque, créez une sous-classe de Container pour ajouter vos propres providers et passez l'instance à create_app(container=...). Lorsque vous travaillez dans le dépôt, enregistrez les services supplémentaires du framework directement dans le conteneur.

Configuration de l'application

La configuration est chargée via une ConfigSource (voir agent_lab/core/config.py) et liée au conteneur DI. Le framework fournit trois sources YAML pour le développement et les tests, sélectionnées automatiquement selon des variables d'environnement :

• config-dev.yml : environnement de développement, activé lorsque DEVELOPING est défini — destiné au débogage dans l'IDE.
• config-test.yml : environnement de test, activé lorsque TESTING est défini — utilisé par la configuration des tests d'intégration.
• config-docker.yml : environnement Docker Compose, activé lorsque DOCKER est défini.

Ces fichiers définissent des paramètres tels que les connexions aux bases de données et l'authentification, et sont réservés au développement et aux tests. En production, utilisez Vault via VaultConfigSource (la source par défaut lorsqu'aucune variable d'environnement n'est définie). Pour fournir la configuration depuis un autre backend, implémentez votre propre ConfigSource et passez-la à create_app(config_source=...). Chaque clé de configuration et variable d'environnement est documentée dans la Référence de configuration.

Modèle de domaine des entités

Consultez le Modèle de domaine des entités pour le modèle de données — les entités et leurs relations utilisées dans l'ensemble de l'application.

Journalisation et observabilité

L'application utilise OpenTelemetry pour la journalisation et l'observabilité ; la mise en place se trouve dans agent_lab/infrastructure/metrics/tracer.py. Les appels FastAPI, HTTPX, LangChain, SQLAlchemy et OpenAI sont instrumentés d'emblée, avec des backends enfichables pour Langfuse et LangWatch. Consultez le guide d'observabilité pour plus de détails.

Tests

Le projet utilise pytest en mettant l'accent sur les tests d'intégration (seuil de couverture : 90 %), avec Testcontainers pour que les tests s'exécutent sur de vrais services dans des conteneurs Docker. Une suite de simulation distincte évalue le comportement des agents de bout en bout avec un LLM-as-judge.

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

La première exécution peut prendre plusieurs minutes, le temps de télécharger les images Docker et les modèles d'embeddings. Consultez le guide des tests pour une vue d'ensemble.

Initialiser pre-commit

Si vous prévoyez de contribuer au code ou de créer de nouveaux agents sur Agent-Lab, installez les hooks pre-commit :

pre-commit install

Cela garantit que votre code respecte les normes de codage du projet avant chaque commit.

Créer des workflows agentiques

Agent-Lab repose sur LangGraph, qui offre un moyen puissant de créer des workflows agentiques à l'aide de LLM. En créer un est un processus simple grâce à l'architecture modulaire et aux classes de base des agents.

Définir une nouvelle implémentation d'agent

L'agent est un concept central d'Agent-Lab : il représente une entité autonome capable d'exécuter des tâches, de prendre des décisions et d'interagir avec d'autres agents ou des systèmes externes. Un agent est une implémentation concrète de l'une des classes de base :

Une classe qui étend WorkflowAgentBase définit :

• un workflow représentant le comportement de l'agent — tâches, prise de décision et interactions avec d'autres agents ou des systèmes externes ;
• des paramètres d'initialisation tels que les prompts (templates Jinja2) et d'autres paramètres qui personnalisent le comportement de l'agent (collections du vector store, température, etc.).

Voici un exemple de paramètres d'initialisation persistés pour un agent qui effectue la transcription et l'analyse de messages vocaux, une fois l'agent créé et stocké dans la base de données :

Plusieurs agents reposant sur la même implémentation peuvent être créés et affinés via l'API REST.

Enregistrer l'agent avec @discoverable_agent

Décorez votre sous-classe d'AgentBase avec @discoverable_agent("<agent_type>"). Ce seul décorateur suffit à enregistrer un agent — il rend l'agent :

• découvrable par le registre des agents (agent_lab/services/agent_types/registry.py),
• résolvable via le conteneur DI, qui l'instancie de manière paresseuse et injecte les extra_deps déclarées,
• valide au niveau de l'API, car le schéma de création d'agent valide dynamiquement agent_type par rapport au registre.

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

Remarque (migration) : les versions précédentes exigeaient de câbler manuellement chaque agent dans container.py, de l'ajouter à registry.py et d'étendre le schéma Pydantic dans agents/schema.py. Ces étapes sont obsolètes — @discoverable_agent s'en charge entièrement. Les extra_deps que vous déclarez sont résolues par nom sur le conteneur (éventuellement dérivé) au moment de l'instanciation.

Si un agent a besoin de collaborateurs en plus d'AgentUtils, exposez-les sous forme de providers sur le conteneur (créez une sous-classe de Container lorsque vous utilisez la bibliothèque) et nommez-les dans extra_deps.

Rendre l'agent découvrable

Le framework n'importe que les modules d'agents qui lui sont indiqués, afin que le décorateur s'exécute :

• Dans le dépôt : placez l'agent sous agent_lab/services/agent_types/ — l'application de référence analyse ce package dans le cadre de DEFAULT_SCAN_PACKAGES (create_app()).

• Comme bibliothèque : passez votre package à create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) — une liste explicite remplace les valeurs par défaut (c'est d'ailleurs ainsi que vous excluez des capacités intégrées) — ou publiez-le depuis un package installé via le groupe d'entry points agent_lab.agents pour que les consommateurs le récupèrent automatiquement :

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

Expérimenter avec l'implémentation de l'agent

Consultez les notebooks pour des exemples de test interactif d'un agent avec Jupyter, en utilisant le même mécanisme d'injection de dépendances. C'est un moyen pratique de prototyper et de valider un comportement dans un environnement maîtrisé — voir le Guide du chercheur.

Interface REST des agents

Une fois un agent enregistré, créez et gérez ses instances via l'API REST — vous pouvez exécuter plusieurs instances configurées de la même implémentation, chacune avec ses propres prompts et paramètres. Consultez la Référence de l'API REST pour le catalogue des points de terminaison et des exemples de requêtes.

Tester l'agent

• Les tests d'intégration (tests/integration/) valident l'agent sur une infrastructure réelle avec pytest et testcontainers.
• Les simulations (tests/simulation/) évaluent le comportement de bout en bout avec un LLM-as-judge. Voir le guide des tests.

Serveur MCP

Consultez le Guide du serveur MCP pour exposer vos agents (et des outils supplémentaires) à des clients MCP tels que Claude Desktop, pour la découverte d'agents, l'historique des dialogues et la communication d'agent à agent.

Étendre le framework

Lorsque vous utilisez Agent-Lab comme bibliothèque, vous façonnez entièrement l'application via create_app() et l'API publique exportée par le package de premier niveau agent_lab — sans jamais modifier le code du 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."],
)

Tout ce qui précède est exporté par agent_lab (voir agent_lab/__init__.py) ; la liste complète des clés de configuration utilisées par ces options figure dans la Référence de configuration.

Contribuer

Le soutien de la communauté est très apprécié. Si vous rencontrez un problème ou avez des suggestions d'amélioration, signalez-les en créant une issue sur notre page GitHub Issues.

Pour contribuer au projet, suivez ces étapes :

1. Forkez le dépôt.
2. Créez une nouvelle branche pour votre fonctionnalité ou votre correctif.
3. Activez les hooks pre-commit en exécutant pre-commit install, apportez vos modifications et commitez-les avec des messages clairs et concis.
4. Assurez-vous que vos modifications passent les hooks pre-commit et le seuil de couverture de 90 % (make test).
5. Poussez vos modifications vers votre dépôt forké.
6. Créez une Pull Request (PR) vers la branche main du dépôt d'origine.

Nous examinerons votre PR et vous ferons part de nos retours. Merci pour vos contributions et votre soutien !

Déploiement en production

Consultez le guide de déploiement pour déployer l'application de référence en production à l'aide des charts Helm et des scripts Terraform fournis.