Démarrage rapide

Ce que vous allez construire

Un acteur minimal et fonctionnel — généré, vérifié et exécuté localement avec PostgreSQL et Redis. Pas encore de code de domaine ; cela prouve le chemin de bout en bout.

Prérequis

Outil	Version
Python	3.11, 3.12 ou 3.13
copier	9.4.0 ou plus récent
Docker	20.10+ (pour PostgreSQL et Redis)
PostgreSQL	14+ (fourni par le fichier compose généré)
Redis	6+ (fourni par le fichier compose généré)

Installez copier avec pip install copier, pipx install copier ou uv tool install copier.

1. Générer l’acteur

copier copy https://github.com/allcare/kaboum my-first-actor --defaults --trust

Avec --defaults, vous répondez à exactement deux questions :

• project_name — minuscules, chiffres et soulignés ; commence par une lettre ; 31 caractères au plus (par exemple myfirst).
• domain_module — le répertoire de domaine de votre acteur, par exemple tasks. Les noms réservés sont rejetés : mesh, agent, api, core, kaoohi, shared, integrations, middleware, models, storage.

Pour tout le reste — framework d’agent, version de Python, métadonnées marketplace — des défauts sensés s’appliquent. Vous avez maintenant un projet complet dans my-first-actor/.

2. L’installer

cd my-first-actor
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Activez l’environnement virtuel et gardez-le activé : le Makefile appelle python directement, donc les cibles make échouent avec « python: No such file or directory » si l’environnement n’est pas dans votre path.

3. Vérifier la configuration

Le src/kaoohi/config.json de l’acteur est dérivé de vos réglages et des métadonnées pyproject — ne l’éditez jamais à la main. Une cible l’émet et le vérifie :

make kaoohi-config

Cela exécute l’émetteur, puis un contrôle de fraîcheur. Sur un rendu neuf le fichier n’existe pas encore, donc python -m src.kaoohi.config_emitter --check échoue à lui seul avant la première émission — préférez make kaoohi-config, qui fait les deux.

4. Lancer les portes qualité

ruff check .
pytest -q

Les deux doivent passer avant que vous ne changiez quoi que ce soit. La suite unitaire n’a pas besoin de base de données — sur le template au moment de la vérification, elle a exécuté 281 tests en moins d’une minute.

5. L’exécuter localement

Démarrez PostgreSQL et Redis, puis l’acteur :

docker compose up -d postgres redis
make run

make run démarre uvicorn sur le port 8080. Vérifiez la santé :

curl http://localhost:8080/health

Vous devriez recevoir un 200 avec le statut et la version de l’acteur. /ready et /metrics sont là aussi, et POST /agent/invoke est l’endpoint de conversation. Pointez votre navigateur sur http://localhost:8080/docs pour l’API interactive complète.

Note : l’application exige PostgreSQL pour démarrer ; les échecs Redis et auth se dégradent en avertissements au lieu de crasher.

Et ensuite

• ](fr/track-a/setup-and-generate/) : ajoutez du vrai code de domaine — modèles, client, outils, migrations — aux sept points d’extension.
• ](fr/publishing/) : construisez l’image, poussez-la vers un registre et enregistrez l’acteur sur Kaoohi.

---

Dernière vérification : 2026-10-13, contre le commit kaboum fbee633.

Étapes réellement exécutées : rendu avec copier copy <checkout kaboum> quickstart-verify --vcs-ref=HEAD --data project_name=kquick --data domain_module=quickdemo --defaults --trust (chemin local, même contenu de template) ; pip install -e ".[dev]" dans un venv neuf (propre) ; make kaoohi-config (émission + contrôle passent, venv activé) ; ruff check . (propre) ; pytest -q (281 passés, 6 sautés, Docker inutile). Deux constats intégrés dans les étapes ci-dessus : le Makefile exige le venv activé, et l’émetteur --check échoue avant la première émission. La forme par URL GitHub de l’étape 1 correspond au flux documenté du template (générer depuis un ref git pour que copier update fonctionne ensuite) ; le rendu par URL lui-même n’a pas été rejoué dans cette vérification.