Optimiser les conversations ClickHouse Assistant avec une couche sémantique

Guide d’utilisation d’AGENTS.md pour fournir une logique métier personnalisée et des instructions spécifiques aux données à l’agent de chat ClickHouse Assistant

L’agent de chat ClickHouse Assistant peut être personnalisé pour comprendre votre logique métier, vos structures de données et votre expertise métier grâce à AGENTS.md — une requête enregistrée spéciale qui sert de couche sémantique au prompt système de l’agent.

En créant un fichier AGENTS.md, vous pouvez fournir des instructions personnalisées injectées au début de chaque conversation afin d’orienter la génération de requêtes SQL et l’analyse des données selon les exigences, calculs et conventions propres à votre organisation.

​

Fonctionnement

Lorsque vous enregistrez une requête nommée “AGENTS.md” (sensible à la casse) dans la Cloud Console :

1. Le agent de chat ClickHouse Assistant charge automatiquement ce fichier lorsqu’un message est envoyé
2. Le contenu est placé dans une balise de contenu structurée, puis injecté dans le prompt système de l’agent
3. Les instructions s’appliquent à toutes les conversations ClickHouse Assistant chat de ce service

​

Création d’AGENTS.md

1. Créez la requête enregistrée

   1. Dans le Cloud Console, créez une nouvelle requête
   2. Nommez-la exactement : “AGENTS.md” (sensible à la casse)
   3. Saisissez vos instructions personnalisées dans l’éditeur de texte de la requête (pas du SQL)
   4. Enregistrez la requête
2. Ajoutez vos instructions

   Structurez vos instructions dans un langage clair et directement exploitable. Incluez :

   • Les règles métier et les calculs
   • Des indications sur la structure des données
   • La terminologie spécifique au domaine
   • Les modèles de requête courants
   • Les règles d’optimisation des performances

​

Bonnes pratiques

​

Considérez le contexte comme une ressource finie

Le contexte est précieux : chaque token entame le « budget d’attention » de l’agent. Comme les humains à la mémoire de travail limitée, les modèles de langage voient leurs performances se dégrader à mesure que le contexte s’allonge. Il faut donc trouver le plus petit ensemble possible de tokens à forte valeur informative qui maximise les chances d’obtenir le résultat souhaité.

​

Trouver le bon niveau de précision

Trouvez le bon équilibre entre deux extrêmes :

• Trop spécifique : coder en dur une logique conditionnelle fragile avec des if-else, ce qui complexifie la maintenance
• Trop vague : des recommandations trop générales qui ne donnent pas de signaux concrets ou supposent à tort un contexte partagé

Le niveau de précision optimal est suffisamment spécifique pour orienter efficacement le comportement, tout en restant assez flexible pour permettre au modèle d’appliquer de bonnes heuristiques. Commencez par un prompt minimal sur le meilleur modèle disponible, puis ajoutez des instructions claires en fonction des modes d’échec observés.

​

Organiser le contenu en sections structurées

Utilisez des balises XML ou des en-têtes Markdown pour créer des sections distinctes et faciles à parcourir :

<background_information>
Context about your data and domain
</background_information>

<calculation_rules>
Specific formulas and business logic
</calculation_rules>

<tool_guidance>
How to use specific ClickHouse features
</tool_guidance>

​

Fournissez des exemples variés et canoniques

Les exemples valent mille mots. Au lieu d’entasser tous les cas limites dans votre prompt, sélectionnez un ensemble ciblé d’exemples variés qui illustrent efficacement le comportement attendu.

​

Restez minimal, mais complet

• Incluez uniquement les instructions fréquemment nécessaires
• Soyez concis : un contexte plus long dégrade les performances à cause de la « dégradation du contexte »
• Supprimez les règles obsolètes ou rarement utilisées
• Veillez à fournir suffisamment d’informations pour orienter le comportement souhaité

Minimal ne signifie pas forcément court. Vous devez fournir suffisamment de détails pour que l’agent adopte le comportement attendu, tout en évitant toute verbosité inutile.

​

Exemple : métriques calculées à partir de données brutes

Indiquez à l’agent lorsque les métriques nécessitent des calculs spécifiques plutôt qu’un accès direct aux colonnes :

<metric_calculations>
IMPORTANT: "active_sessions" is NOT a column. It must be calculated.

To calculate active sessions:
COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions

This counts unique combinations of session and user identifiers.

When the user asks for "active sessions" or "session count", always use this formula:
SELECT
    date,
    COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions
FROM events
GROUP BY date;

</metric_calculations>

​

Exemple : Règles de logique métier

Définissez des calculs et des catégories propres à votre domaine :

<business_rules>
Revenue Calculation:
- Exclude refunded transactions: WHERE transaction_status != 'refunded'
- Apply regional tax rates using CASE expressions
- Use MRR for subscriptions:
  SUM(CASE
    WHEN billing_cycle = 'monthly' THEN amount
    WHEN billing_cycle = 'yearly' THEN amount / 12
    ELSE 0
  END) AS mrr

Traffic Source Classification:
Use CASE expression to categorize:
CASE
  WHEN traffic_source IN ('google', 'bing', 'organic') THEN 'Organic Search'
  WHEN traffic_source IN ('facebook', 'instagram', 'social') THEN 'Social Media'
  WHEN traffic_source = 'direct' THEN 'Direct'
  ELSE 'Other'
END AS source_category

Customer Segmentation:
- Enterprise: annual_contract_value >= 100000
- Mid-Market: annual_contract_value >= 10000 AND annual_contract_value < 100000
- SMB: annual_contract_value < 10000

Always include these categorizations when generating traffic or revenue reports.
</business_rules>

​

Exemple : particularités des structures de données

Consignez les formats de données non conventionnels ou les choix de schéma hérités :

<data_structure_notes>
The user_status column uses numeric codes, not strings:
- 1 = 'active'
- 2 = 'inactive'
- 3 = 'suspended'
- 99 = 'deleted'

When filtering or displaying user status, always use:
CASE user_status
  WHEN 1 THEN 'active'
  WHEN 2 THEN 'inactive'
  WHEN 3 THEN 'suspended'
  WHEN 99 THEN 'deleted'
END AS status_label

The product_metadata column contains JSON strings that must be parsed:
SELECT
    product_id,
    JSONExtractString(product_metadata, 'category') AS category,
    JSONExtractInt(product_metadata, 'inventory_count') AS inventory
FROM products;
</data_structure_notes>

​

Exemple : terminologie métier

Faites correspondre les termes métier à leur implémentation technique :

<terminology>
When users refer to "conversions", they mean:
- For e-commerce: transactions WHERE transaction_type = 'purchase'
- For SaaS: subscriptions WHERE subscription_status = 'active' AND first_payment_date IS NOT NULL

"Churn" is calculated as:
COUNT(DISTINCT user_id) WHERE last_active_date < today() - INTERVAL 90 DAY
AND previous_subscription_status = 'active'

"DAU" (Daily Active Users) means:
COUNT(DISTINCT user_id) WHERE activity_date = today()

"Qualified leads" must meet ALL criteria:
- lead_score >= 70
- company_size >= 50
- budget_confirmed = true
- contact_role IN ('Director', 'VP', 'C-Level')
</terminology>