00 Configuration

Résultat

Un dépôt cloné avec un environnement virtuel Python installé, un fichier .env contenant les identifiants OpenRouter, ClickHouse Cloud et Langfuse Cloud, une base arena dans ClickHouse Cloud initialisée avec des données e-commerce synthétiques, et le dashboard local accessible sur http://localhost:5174. L'onglet Leaderboard est encore vide : c'est normal jusqu'au Module 01.

Pourquoi

Agent Arena repose sur un seul cœur d'agent NL→SQL (agents/) réutilisé par deux appelants : le harness du benchmark (eval/harness.py) et l'API de service en direct (serving/api.py). La démonstration et le benchmark empruntent donc exactement le même chemin de code : mêmes modèles de prompt, même client de modèle, même sandbox SQL en lecture seule. Les chiffres du benchmark prédisent ainsi de manière fiable le comportement en production, au lieu de provenir d'un « harness d'évaluation » distinct qui divergerait discrètement de ce qui est publié.

Remarquez que Langfuse fait partie des trois comptes configurés dans ce tout premier module, avant le choix du modèle et avant la première question. C'est volontaire : Langfuse n'est pas ajouté une fois le chatbot terminé ; c'est l'outil qui exécute la compétition au Module 01, mesure le gagnant hors ligne au Module 02, détecte un angle mort de production au Module 03, soutient l'enquête humaine au Module 04, puis prouve et surveille l'amélioration au Module 05. Un projet et une piste de preuves continue. Tous les modules suivants reposent sur ce chemin de code et ce projet Langfuse ; bien configurer ici les trois comptes et la base initialisée rend le reste de l'atelier fluide.

Concepts — sous le capot

Trois piliers, trois rôles, reliés dès ce premier module :

• OpenRouter — une API compatible OpenAI devant toutes les familles de modèles de l'atelier (Anthropic, OpenAI, Google, DeepSeek, Qwen et Z.ai). Plutôt que de gérer six SDK et six ensembles d'identifiants, le cœur (agents/) utilise un client unique pour atteindre les six modèles de config.yaml. C'est ce qui permet une comparaison équitable au Module 01 : chaque modèle n'est qu'une chaîne model= derrière le même endpoint et le même format de requête.
• ClickHouse — la base de données de l'application. Elle contient les données métier, les tables e-commerce synthétiques que vous allez initialiser, derrière les vues v_*. L'agent ne peut effectuer que des SELECT sur les vues v_* : jamais sur les tables brutes et jamais en écriture. Ce contrat stable, documenté et en lecture seule est aussi imposé par agents/sqlguard.py : il analyse le SQL généré, rejette tout ce qui n'est pas une instruction unique SELECT/WITH…SELECT et bloque une liste de mots-clés d'écriture ou DDL (INSERT, UPDATE, DELETE, DROP, ALTER, SYSTEM, …), même dans une instruction par ailleurs valide.
• Langfuse — le stockage de l'évaluation, du leaderboard et de l'observabilité. Il est connecté maintenant, avant tout choix de modèle, car il ne s'agit pas d'un ajout tardif : il note la compétition au Module 01, permet d'analyser la qualité au Module 02, détecte les échecs de production au Module 03, porte la revue humaine au Module 04 et valide le trafic futur au Module 05. Un projet et une piste continue de traces, feedback, scores, annotations et datasets.

Objectif

Trois ensembles d'identifiants dans .env, une base arena initialisée avec les vues v_* que l'agent interrogera, et le dashboard local accessible dans un navigateur.

Étape 1 — Créer trois comptes

Vous avez besoin d'identifiants API pour trois services avant d'ouvrir le terminal :

Gardez-les à portée de main : vous allez les coller dans .env.

Réglage de confidentialité OpenRouter requis pour Qwen

Dans OpenRouter, ouvrez Settings → Privacy → Data Policies → Zero Data Retention et désactivez Non-frontier ; l'interrupteur doit être gris. Qwen appartient au groupe non-frontier d'OpenRouter et son endpoint Alibaba disponible n'est pas éligible lorsque Zero Data Retention est imposé pour ce groupe. Si le réglage reste actif, qwen/qwen3.7-flash échoue avec No endpoints available matching your guardrail restrictions and data policy même si la clé API et le slug du modèle sont valides.

L'atelier envoie des questions et schémas e-commerce synthétiques. Pour de vraies charges, examinez les exigences de confidentialité de votre organisation avant d'assouplir une politique ZDR.

Étape 2 — Cloner le dépôt

Agent Arena se trouve dans le monorepo ClickHouse_Demos, sous workshops/agent_arena dans la branche build-workshop-v1. Clonez le dépôt entier, puis entrez dans ce sous-répertoire ; toutes les commandes suivantes supposent que vous vous y trouvez :

git clone --branch build-workshop-v1 --single-branch https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos/workshops/agent_arena

Étape 3 — Créer un environnement virtuel et installer les dépendances

python3.11 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Étape 4 — Configurer .env

Copiez le fichier d'exemple :

cp .env.example .env

.env

Renseignez les valeurs de l'étape 1 ; chacune est vide ou factice dans .env.example :

# ClickHouse Cloud (business data queried by the agent)
export CLICKHOUSE_CLOUD_HOST=xxx.clickhouse.cloud
export CLICKHOUSE_CLOUD_USER=default
export CLICKHOUSE_CLOUD_PASSWORD=
export CLICKHOUSE_CLOUD_DATABASE=arena
export ARENA_RO_PASSWORD=
# OpenRouter (LLM provider)
export OPENROUTER_API_KEY=sk-or-...
export OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
# Langfuse Cloud (eval store + tracing)
export LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...

Rôle de chaque bloc :

• CLICKHOUSE_CLOUD_* — les identifiants administrateur de votre service ClickHouse Cloud. La configuration les utilise une fois pour créer la base arena et un utilisateur dédié en lecture seule (arena_ro) que l'agent emploie pendant le reste de l'atelier.
• ARENA_RO_PASSWORD — choisissez un mot de passe ; il deviendra celui de arena_ro lors de la création de l'utilisateur.
• OPENROUTER_* — votre clé OpenRouter et son URL de base. Tous les modèles de config.yaml passent par cet endpoint.
• LANGFUSE_* — l'hôte et les clés du projet Langfuse Cloud. Toutes les traces, scores et datasets de l'atelier y résident, de la première Arena au Module 01 à l'amélioration surveillée au Module 05.

Étape 5 — Initialiser ClickHouse avec des données e-commerce synthétiques

Cette commande crée la base arena, l'utilisateur en lecture seule arena_ro, génère directement dans ClickHouse des données e-commerce synthétiques (clients, produits, commandes, lignes de commande et événements), puis construit les vues v_* interrogées par l'agent :

source .env && scripts/arena.sh up

Chaque agent, prompt et SQL doré de l'atelier interroge les vues v_customers, v_products, v_orders, v_order_items et v_events, jamais les tables brutes.

scripts/arena.sh up démarre aussi l'API et l'interface web du dashboard. À la fin, ouvrez http://localhost:5174. L'onglet Leaderboard restera vide jusqu'à la compétition du Module 01.

À quoi ressemble une exécution saine. scripts/arena.sh up affiche, dans l'ordre :

1. ClickHouse: business database + read-only agent user — la base arena et l'utilisateur dédié arena_ro sont créés.
2. Seeding ClickHouse directly + views + schema context — une ligne clickhouse: inserted <N> into <table> par table (customers, products, orders, order_items, events), puis done, puis la création des vues v_* et du contexte de schéma lu par l'agent.
3. Starting dashboard API (:8000) + web UI (:5174) — deux lignes [ready]. Si l'une affiche [NOT up], le port est probablement occupé ; consultez le chemin de log indiqué (.run/dashboard-api.log ou .run/web.log).

Vous pouvez revérifier l'ensemble avec scripts/arena.sh status, qui affiche l'état des serveurs et le nombre de lignes de chaque vue v_*.

Comment vérifier que vous avez terminé

• .env contient de vraies valeurs, et non des placeholders, pour CLICKHOUSE_CLOUD_*, OPENROUTER_* et LANGFUSE_*.
• scripts/arena.sh up s'est terminé sans erreur.
• http://localhost:5174 s'ouvre dans un navigateur et affiche l'onglet Leaderboard ; il est normal qu'il soit vide.

Exercice — casser puis diagnostiquer une connexion

Apprenez à reconnaître la signature d'une mauvaise valeur .env en la provoquant volontairement, sans enjeu :

1. Ouvrez .env et modifiez un caractère de ARENA_RO_PASSWORD, ou commentez temporairement la ligne.
2. Relancez source .env && scripts/arena.sh up. Les étapes administrateur ClickHouse, qui utilisent les identifiants administrateur, devraient réussir ; observez à quel moment le chemin en lecture seule, toute connexion en tant que arena_ro, commence à se plaindre.
3. Lisez attentivement le message : s'agit-il d'une erreur d'authentification, d'un utilisateur inexistant ou d'un silence suivi d'un timeout ? Notez votre cas.
4. Restaurez le bon ARENA_RO_PASSWORD, relancez scripts/arena.sh up et confirmez que tout se termine correctement.

C'est le même réflexe de diagnostic que vous utiliserez quand la configuration d'un collègue « ne fonctionne pas » : relier le texte de l'erreur à celui des trois services qui est mal configuré, au lieu de tout revérifier.

Récapitulatif

Vous disposez d'une base ClickHouse initialisée, des identifiants des trois services — Langfuse compris, connecté avant tout choix de modèle — et du dashboard local. Tous les modules suivants réutilisent le même environnement et le même projet Langfuse ; aucune autre configuration n'est nécessaire.

État final

Environnement prêt. Passez à 01 Sélectionner le modèle de base pour exécuter la compétition sur ces données.