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.

​

Cómo funciona

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

​

Crear AGENTS.md

1. 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
2. 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

​

Buenas prácticas

​

Considera el contexto como un recurso finito

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.

​

Encuentra el nivel de detalle adecuado

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.

​

Organiza con secciones bien estructuradas

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

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

​

Proporcione ejemplos diversos y canónicos

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.

​

Que sea mínimo, pero completo

• 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

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.

​

Ejemplo: Métricas calculadas a partir de datos en bruto

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

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

​

Ejemplo: Reglas de lógica de negocio

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

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

​

Ejemplo: peculiaridades de la estructura de datos

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

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

​

Ejemplo: terminología del dominio

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

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