> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<div id="how-it-works">
  ## Fonctionnement
</div>

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

<div id="creating-agents-md">
  ## Création d’AGENTS.md
</div>

<Steps>
  <Step>
    ### Créez la requête enregistrée

    1. Dans le Cloud Console, créez une nouvelle requête
    2. Nommez-la exactement : **"AGENTS.md"** (respecter 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
  </Step>

  <Step>
    ### 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
  </Step>
</Steps>

<div id="best-practices">
  ## Bonnes pratiques
</div>

<div id="finite-resource">
  ### Considérez le contexte comme une ressource finie
</div>

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

<div id="right-altitude">
  ### Trouver le bon niveau de précision
</div>

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.

<div id="structured-sections">
  ### Organiser le contenu en sections structurées
</div>

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

```xml theme={null}
<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>
```

<div id="canonical-examples">
  ### Fournissez des exemples variés et canoniques
</div>

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.

<div id="minimal-complete">
  ### Restez minimal, mais complet
</div>

* 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é

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

<div id="example-calculated-metrics">
  ## Exemple : métriques calculées à partir de données brutes
</div>

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

```xml theme={null}
<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>
```

<div id="example-business-logic">
  ## Exemple : Règles de logique métier
</div>

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

```xml theme={null}
<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>
```

<div id="example-data-quirks">
  ## Exemple : particularités des structures de données
</div>

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

```xml theme={null}
<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>
```

<div id="example-terminology">
  ## Exemple : terminologie métier
</div>

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

```xml theme={null}
<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>
```