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

# Optimizar las conversaciones de ClickHouse Assistant con una capa semántica

> Guía para usar AGENTS.md para proporcionar al agente de chat de ClickHouse Assistant lógica de negocio personalizada e instrucciones específicas de los datos

El agente de chat de ClickHouse Assistant se puede personalizar para que comprenda la lógica de negocio, las estructuras de datos y el conocimiento del dominio específicos de su organización mediante **AGENTS.md**, una consulta guardada especial que actúa como una capa semántica sobre el prompt del sistema del agente.

Al crear un archivo AGENTS.md, puede proporcionar instrucciones personalizadas que se insertan al inicio de cada conversación para orientar la generación de consultas SQL y el análisis de datos según los requisitos, cálculos y convenciones específicos de su organización.

<div id="how-it-works">
  ## Cómo funciona
</div>

Cuando guarda una consulta llamada "AGENTS.md" (sensible a mayúsculas y minúsculas) en la Cloud Console:

1. El agente de chat de ClickHouse Assistant carga automáticamente este archivo cuando se envía un mensaje
2. El contenido se coloca dentro de una etiqueta de contenido estructurado y se inyecta en el prompt del sistema del agente
3. Las instrucciones se aplican a todas las conversaciones de chat de ClickHouse Assistant de ese servicio

<div id="creating-agents-md">
  ## Crear AGENTS.md
</div>

<Steps>
  <Step>
    ### Crea la consulta guardada

    1. En la Cloud Console, crea una consulta nueva
    2. Asígnale exactamente este nombre: **"AGENTS.md"** (sensible a mayúsculas y minúsculas)
    3. Escribe tus instrucciones personalizadas en el editor de texto de la consulta (no SQL)
    4. Guarda la consulta
  </Step>

  <Step>
    ### Añade tus instrucciones

    Estructura tus instrucciones con un lenguaje claro y práctico. Incluye:

    * Reglas de negocio y cálculos
    * Indicaciones sobre la estructura de los datos
    * Terminología específica del dominio
    * Patrones de consulta habituales
    * Reglas de optimización del rendimiento
  </Step>
</Steps>

<div id="best-practices">
  ## Buenas prácticas
</div>

<div id="finite-resource">
  ### Considera el contexto como un recurso finito
</div>

El contexto es valioso: cada token consume el "presupuesto de atención" del agente. Al igual que los seres humanos, cuya memoria de trabajo es limitada, los modelos de lenguaje ven degradado su rendimiento a medida que aumenta el contexto. Esto significa encontrar el **conjunto más pequeño posible de tokens con alta señal** que maximice la probabilidad de obtener el resultado deseado.

<div id="right-altitude">
  ### Encuentra el nivel de detalle adecuado
</div>

Logra un equilibrio entre dos extremos:

* **Demasiado específico**: Codificar de forma rígida una lógica `if-else` frágil que genera complejidad de mantenimiento
* **Demasiado vago**: Orientación de alto nivel que no ofrece señales concretas o que asume erróneamente un contexto compartido

El nivel de detalle óptimo es lo bastante específico como para guiar el comportamiento de forma eficaz y, al mismo tiempo, lo bastante flexible como para que el modelo aplique heurísticas sólidas. Empieza con un prompt mínimo en el mejor modelo disponible y, después, añade instrucciones claras en función de los modos de fallo observados.

<div id="structured-sections">
  ### Organiza con secciones bien estructuradas
</div>

Usa etiquetas XML o encabezados de Markdown para crear secciones diferenciadas y fáciles de recorrer:

```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">
  ### Proporcione ejemplos diversos y canónicos
</div>

Los ejemplos son las «imágenes que valen más que mil palabras». En lugar de incluir todos los casos extremos en su `prompt`, seleccione un conjunto acotado de ejemplos diversos que ilustre con eficacia el comportamiento esperado.

<div id="minimal-complete">
  ### Que sea mínimo, pero completo
</div>

* Incluye solo las instrucciones que se necesitan con frecuencia
* Sé conciso: un contexto más amplio degrada el rendimiento debido al "deterioro del contexto"
* Elimina las reglas obsoletas o que rara vez se usan
* Asegúrate de incluir información suficiente para orientar el comportamiento deseado

<Tip>
  Que sea mínimo no significa necesariamente que deba ser corto. Necesitas suficiente detalle para garantizar que el agente se ajuste al comportamiento esperado; simplemente evita la verbosidad innecesaria.
</Tip>

<div id="example-calculated-metrics">
  ## Ejemplo: Métricas calculadas a partir de datos en bruto
</div>

Indica al agente cuándo las métricas requieren cálculos específicos en lugar de acceder directamente a las columnas:

```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">
  ## Ejemplo: Reglas de lógica de negocio
</div>

Defina cálculos y clasificaciones específicos del dominio:

```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">
  ## Ejemplo: peculiaridades de la estructura de datos
</div>

Documenta formatos de datos no convencionales o decisiones heredadas sobre el esquema:

```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">
  ## Ejemplo: terminología del dominio
</div>

Asigne los términos empresariales a la implementación técnica:

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