Otimizando as conversas do ClickHouse Assistant com uma camada semântica

O agente de chat do ClickHouse Assistant pode ser personalizado para entender a regra de negócio específica, as estruturas de dados e o conhecimento de domínio da sua organização por meio do AGENTS.md — uma consulta salva especial que atua como uma camada semântica sobre o prompt de sistema do agente. Ao criar um arquivo AGENTS.md, você pode fornecer instruções personalizadas que são injetadas no início de cada conversa para orientar a geração de consultas SQL e a análise de dados com base nos requisitos, cálculos e convenções exclusivos da sua organização.

Como funciona

Quando você salva uma consulta chamada “AGENTS.md” (sensível a maiúsculas e minúsculas) no Cloud Console:

O agente de chat do ClickHouse Assistant carrega esse arquivo automaticamente quando uma mensagem é enviada
O conteúdo é inserido em uma tag de conteúdo estruturado e injetado no prompt de sistema do agente
As instruções são aplicadas a todas as conversas do ClickHouse Assistant chat nesse serviço

Criando AGENTS.md

Crie a consulta salva

No Cloud Console, crie uma nova consulta
Dê a ela exatamente este nome: “AGENTS.md” (diferencia maiúsculas de minúsculas)
Escreva suas instruções personalizadas no editor de texto da consulta (não SQL de fato)
Salve a consulta

Adicione suas instruções

Estruture suas instruções com uma linguagem clara e objetiva. Inclua:

Regras de negócio e cálculos
Orientações sobre a estrutura de dados
Terminologia específica do domínio
Padrões comuns de consulta
Regras de otimização de desempenho

Boas práticas

Trate o contexto como um recurso finito

O contexto é precioso — cada token consome o “orçamento de atenção” do agente. Assim como os humanos têm memória de trabalho limitada, os modelos de linguagem sofrem degradação de desempenho à medida que o contexto cresce. Isso significa encontrar o menor conjunto possível de tokens mais informativos que maximize a probabilidade do resultado desejado.

Encontre o nível certo de detalhe

Busque um equilíbrio entre dois extremos:

Específico demais: Codificar de forma rígida uma lógica if-else frágil, que gera instabilidade e aumenta a complexidade de manutenção
Vago demais: Orientações genéricas que não fornecem sinais concretos ou pressupõem, de forma equivocada, um contexto compartilhado

O nível ideal de detalhe é específico o suficiente para orientar o comportamento com eficácia, mas flexível o bastante para que o modelo aplique heurísticas robustas. Comece com um prompt mínimo no melhor modelo disponível e, em seguida, adicione instruções claras com base nos modos de falha observados.

Organize em seções estruturadas

Use tags XML ou cabeçalhos Markdown para criar seções distintas e fáceis de consultar:

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

Forneça exemplos diversos e canônicos

Os exemplos são como “imagens que valem mais que mil palavras”. Em vez de abarrotar seu prompt com todos os casos extremos, selecione um conjunto enxuto e diverso de exemplos que represente com clareza o comportamento esperado.

Mantenha o mínimo, mas sem deixar de ser completo

Inclua apenas instruções necessárias com frequência
Seja conciso — contexto demais prejudica o desempenho devido à “deterioração do contexto”
Remova regras desatualizadas ou raramente usadas
Garanta informações suficientes para orientar o comportamento desejado

Mínimo não significa necessariamente curto. Você precisa de detalhes suficientes para garantir que o agente siga o comportamento esperado, apenas evite verbosidade desnecessária.

Exemplo: Métricas calculadas a partir de dados brutos

Oriente o agente quando as métricas exigirem cálculos específicos, em vez de acesso direto à coluna:

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

Exemplo: Regras de negócio

Defina cálculos e classificações específicos do domínio:

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

Exemplo: peculiaridades da estrutura de dados

Documente formatos de dados não convencionais ou decisões herdadas relacionadas ao schema:

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

Exemplo: terminologia do domínio

Relacione os termos de negócio à implementação 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>

ClickHouse Cloud

Bring Your Own Cloud

Otimizando as conversas do ClickHouse Assistant com uma camada semântica

Como funciona

Criando AGENTS.md

Crie a consulta salva

Adicione suas instruções

Boas práticas

Trate o contexto como um recurso finito

Encontre o nível certo de detalhe

Organize em seções estruturadas

Forneça exemplos diversos e canônicos

Mantenha o mínimo, mas sem deixar de ser completo

Exemplo: Métricas calculadas a partir de dados brutos

Exemplo: Regras de negócio

Exemplo: peculiaridades da estrutura de dados

Exemplo: terminologia do domínio

​Como funciona

​Criando AGENTS.md

​Crie a consulta salva

​Adicione suas instruções

​Boas práticas

​Trate o contexto como um recurso finito

​Encontre o nível certo de detalhe

​Organize em seções estruturadas

​Forneça exemplos diversos e canônicos

​Mantenha o mínimo, mas sem deixar de ser completo

​Exemplo: Métricas calculadas a partir de dados brutos

​Exemplo: Regras de negócio

​Exemplo: peculiaridades da estrutura de dados

​Exemplo: terminologia do domínio

Como funciona

Criando AGENTS.md

Crie a consulta salva

Adicione suas instruções

Boas práticas

Trate o contexto como um recurso finito

Encontre o nível certo de detalhe

Organize em seções estruturadas

Forneça exemplos diversos e canônicos

Mantenha o mínimo, mas sem deixar de ser completo

Exemplo: Métricas calculadas a partir de dados brutos

Exemplo: Regras de negócio

Exemplo: peculiaridades da estrutura de dados

Exemplo: terminologia do domínio