El agente del 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.
Cuando guarda una consulta llamada “AGENTS.md” (sensible a mayúsculas y minúsculas) en la Cloud Console:
- El agente de chat de ClickHouse Assistant carga automáticamente este archivo cuando se envía un mensaje
- El contenido se coloca dentro de una etiqueta de contenido estructurado y se inyecta en el prompt del sistema del agente
- Las instrucciones se aplican a todas las conversaciones de chat de ClickHouse Assistant de ese servicio
Crea la consulta guardada
- En la Cloud Console, crea una consulta nueva
- Asígnale exactamente este nombre: “AGENTS.md” (sensible a mayúsculas y minúsculas)
- Escribe tus instrucciones personalizadas en el editor de texto de la consulta (no SQL)
- Guarda la consulta
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
Considera el contexto como un recurso finito
Encuentra el nivel de detalle adecuado
- 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
<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
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
<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
<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
<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
<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>
