Um agente de dados de ponta a ponta

Cerca de 28 minutos min de leitura, com 6 exemplos em 8 seções.

Edição 2026.11.15 Exemplos aprovados em 19 de nov de 2026 78 de 78 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.15. Leia o original

Ao final deste capítulo, você será capaz de construir o armazém de dados da loja, fazer com que um modelo de linguagem com respostas gravadas escreva SQL para uma pergunta de negócio, executar esse SQL e identificar o número errado que ele retorna, responder à mesma pergunta a partir de uma métrica definida e avaliar as duas abordagens com cinco perguntas de referência. Trata-se do resultado completo deste livro em forma preliminar: cada capítulo seguinte torna uma parte dele sólida.

O pedido que este livro atende costuma chegar em uma frase: deixe as pessoas perguntarem aos dados. Alguém da área financeira quer a receita líquida por região do mês passado sem esperar por um painel, e alguém lhe entrega um modelo de linguagem. A construção óbvia fornece ao modelo o esquema do armazém e a pergunta, executa o SQL que ele escreve e mostra o resultado. Em uma pergunta escolhida a dedo, essa construção muitas vezes funciona, o que basta para uma demonstração; nas cinco perguntas de referência deste livro, ela acerta 0 of 5. Suas falhas são o problema, porque a maioria delas não parece falha. Uma consulta que não roda é um erro que alguém vê. Uma consulta que roda e retorna um número alguns por cento acima do correto vai para um slide.

Este capítulo constrói primeiro a versão óbvia, executa-a e mostra exatamente onde o número dela está errado. Em seguida, constrói a versão mais simples da alternativa que o livro recomenda: um agente que não enxerga tabelas, apenas uma métrica definida, e que informa quando a métrica não cobre uma pergunta. As duas são avaliadas com as mesmas cinco perguntas, com respostas conferidas, o hábito do qual o restante do livro depende.

Você precisa de Python 3.12.15 e de SQL, e de mais nada: nenhuma GPU, nenhuma conta em nuvem e nenhuma chave de API. Todo exemplo roda offline no DuckDB 2.0.0, com dados que o próprio livro gera, e toda resposta de modelo que ele usa foi gravada uma vez a partir de um modelo aberto e é reproduzida a partir de um arquivo.

Esta parte ainda não foi traduzida, por isso está em inglês.

Meet the shop and its warehouse

Última alteração na edição 2026.11.15

An agent that answers questions from a warehouse can only be as right as the warehouse's definitions let it be. Real warehouses hold more than tables: they hold decisions about what counts as an order, which currency a total is in and which day a timestamp belongs to. Those decisions live in the marts, in the SQL that built them and in the heads of the people who wrote it. So to see where an agent goes wrong, you need a warehouse with those decisions in it, and the traps they create.

This book follows one case throughout: an online shop that sells outdoor and camping gear in three regions, EMEA, AMER and APAC, which we call the shop. It has no brand name and stands for no real business. Its data is generated by the book's own code, lib/shop_data.py, from one fixed seed, so every reader builds exactly the same rows. Orders run from 2024-02-01 to 2026-06-30, and nothing in the data depends on the day you run an example.

The shop's warehouse, which every example queries, is a DuckDB database with two schemas, as an analytics engineer would build them. The raw schema holds what the source systems loaded: orders, order lines, refunds, customers, products, sessions, marketing spend and exchange rates. The analytics schema holds the marts built from the raw tables in SQL, such as fct_orders, one row per real order with its amounts in euros. lib/warehouse.py does the build. Its connect() generates the data, loads raw, runs the SQL that builds analytics, and returns a connection that can read but not write, with access to other files switched off.

The row counts are the quickest way to see them, so the example builds the warehouse and prints them.

load-the-warehouse.py Python 3.12.15 · duckdb 2.0.0 Aprovado
"""Build the shop's warehouse from its seed and list every table with its row count. The point about test orders rests on the `raw.orders` and `analytics.fct_orders` rows; the last two lines give the shop's test orders and its cancelled orders."""from lib.shop_data import SHOP_SEEDfrom lib.warehouse import connect, table_sizescon = connect()                  # generates the shop, loads raw, builds the marts, reopens read-onlyprint(f"seed: {SHOP_SEED}")for table, rows in table_sizes(con):    print(f"{table}: {rows:,}")# The trailing comma unpacks the one row this query returns. order_date_local is the order's day in its# region's time zone, the day sales are counted on; is_test marks orders placed from the shop's test accounts.(first, last, test_orders, cancelled), = con.execute("""    SELECT (SELECT min(order_date_local) FROM analytics.fct_orders),           (SELECT max(order_date_local) FROM analytics.fct_orders),           (SELECT count(*) FROM raw.orders WHERE is_test),           (SELECT count(*) FROM analytics.fct_orders WHERE status = 'cancelled')""").fetchall()print(f"first order day: {first}")print(f"last order day: {last}")print(f"test orders in raw.orders: {test_orders}")print(f"cancelled orders in fct_orders: {cancelled}")
Saídapython load-the-warehouse.py
seed: 2718
raw.customers: 3,100
raw.fx_rates: 2,649
raw.marketing_spend: 2,643
raw.order_lines: 38,439
raw.orders: 15,000
raw.products: 120
raw.refunds: 1,077
raw.sessions: 60,000
analytics.dim_customers: 3,040
analytics.dim_date: 912
analytics.dim_products: 120
analytics.fct_order_lines: 38,071
analytics.fct_orders: 14,856
analytics.fct_refunds: 1,068
analytics.fct_sessions: 60,000
analytics.orders_legacy: 15,000
first order day: 2024-02-01
last order day: 2026-06-30
test orders in raw.orders: 144
cancelled orders in fct_orders: 819

The counts already show three decisions, and the first is that the mart drops the shop's own test orders. raw.orders holds 15,000 orders and analytics.fct_orders holds 14,856, so the 144 test orders, placed from the shop's test accounts, never reach the mart. The customers shrink between raw.customers and analytics.dim_customers for another reason: some customers signed up twice, with emails that differ only in case, and test accounts are left out. The mart keeps the 819 cancelled orders, each with its status, because some questions are about cancellations.

Other decisions aren't visible in a count. EMEA prices include VAT and AMER and APAC prices don't, so gross and net revenue differ by region. Timestamps are stored in UTC, while the shop counts sales on each region's local business day. The shop's fiscal year starts on February 1, and is named for the year it ends in. And analytics.orders_legacy, an older mart that old dashboards still read, has a column called revenue that holds a different number: gross, tax included, test orders kept. Nothing in the schema says which of these rules applies to which question.

Working rule: Build the agent against a warehouse that has your real traps in it: test rows, cancelled orders, several currencies, local business days, a fiscal calendar and at least one legacy table with a tempting name. Generate it from a seed when you can't share production data, so anyone can rebuild it. A clean demo schema hides exactly the failures you need to see.

Faça uma pergunta e receba SQL de um modelo

Última alteração na edição 2026.11.12

Com o armazém de dados da loja construído, o próximo passo óbvio é deixar um modelo consultá-lo. O texto para SQL apenas com o esquema significa que o modelo recebe o nome e o tipo de cada coluna e a pergunta da pessoa, e mais nada, e escreve o SQL. Na nossa experiência, é aí que muitas primeiras versões começam, porque o esquema é a única descrição do armazém que existe, e o banco de dados a mantém atualizada. O que ele deixa de fora são as definições, que o esquema não guarda.

Um livro cujos exemplos chamassem um modelo daria uma resposta diferente a cada execução, e precisaria de uma chave de API. Por isso, cada resposta do modelo neste livro é gravada. Uma gravação é um conjunto salvo de respostas do modelo com um manifesto, feito uma vez por um script na pasta recordings/ do repositório e reproduzido pelos exemplos. O modelo é o Qwen3-4B-Instruct-2507, que a Qwen publica sob a licença Apache 2.0. Ele tem 4.0 bilhões de parâmetros e responde sem uma fase de raciocínio separada, de modo que a resposta contém apenas a resposta final (ficha do modelo da Qwen). Usamos uma quantização de 4 bits dele, um arquivo de cerca de 2.5 GB fixado pelo seu hash SHA-256 (o arquivo), em quatro threads de CPU com llama-cpp-python, de modo que qualquer pessoa possa gravá-lo novamente sem GPU.

As configurações de amostragem são as que a Qwen recomenda para este modelo: temperature 0.7, top-p 0.8, top-k 20 e min-p 0 (model card da Qwen). A semente é reiniciada antes de cada chamada. As respostas são limitadas a 384 tokens para SQL e 256 nos demais casos. Esse limite é uma escolha nossa, para manter uma execução de gravação curta em CPU, onde a Qwen sugere 16,384. O manifest.json de cada gravação registra o script, o modelo e o hash do seu arquivo, o hash do prompt, a amostragem, a data e o tempo de cada chamada.

Do lado dos exemplos, lib/model.py fornece RecordedModel("schema-only-sql"), que reproduz essa gravação. Ele procura cada resposta pelo SHA-256 das mensagens exatas enviadas. Um prompt que difira em um único caractere não tem gravação, e a reprodução para com um erro em vez de devolver uma resposta a outro prompt. O próprio prompt é uma constante em lib/prompts.py, SCHEMA_ONLY_SQL, compartilhada pelo script de gravação e pelos exemplos.

A pergunta é uma que a equipe financeira faz todo mês: "Qual foi a receita líquida em cada região em março de 2026?" Ela também é gq-002, uma pergunta de referência com resposta conferida; a próxima seção testa a resposta contra ela. Antes de julgar o número, leia o SQL que o modelo escreve.

first-question-to-sql.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Send the warehouse's schema and one question to the recorded model, and print the SQL it wrote. The prose reads that SQL for its table, its columns and its date filter, against the `analytics.fct_orders` line printed above it."""from lib.golden import load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.warehouse import connect, describe_schemaschema = describe_schema(connect())# gq-002 is net revenue in each region in March 2026, the question the prose follows.question = next(q for q in load_golden() if q.question_id == "gq-002")messages = schema_only_messages(schema, question.question)# Each table's schema is one CREATE TABLE statement, so counting them counts the tables.print(f"tables in the prompt: {schema.count('CREATE TABLE')}")# The trailing space makes this match the whole table name, not a longer one that starts the same way.print(next(line for line in schema.splitlines() if "analytics.fct_orders " in line))model = RecordedModel("schema-only-sql")       # replays the pinned model's real repliescall = model.call_for(messages)print(f"prompt tokens: {call['prompt_tokens']}")print(f"question: {question.question}")print(call["reply"])
Saídapython first-question-to-sql.py
tables in the prompt: 16
CREATE TABLE analytics.fct_orders (order_id INTEGER, customer_id INTEGER, region VARCHAR, country VARCHAR, channel VARCHAR, status VARCHAR, placed_at TIMESTAMP, order_date_local DATE, currency VARCHAR, line_count BIGINT, gross_revenue_eur DECIMAL(12,2), net_revenue_eur DECIMAL(12,2), discount_eur DECIMAL(12,2), tax_eur DECIMAL(12,2), _loaded_at TIMESTAMP);
prompt tokens: 827
question: What was net revenue in each region in March 2026?
```sql
SELECT
    region,
    SUM(net_revenue_eur) AS net_revenue
FROM
    analytics.fct_orders
WHERE
    order_date_local >= '2026-03-01'
    AND order_date_local < '2026-04-01'
GROUP BY
    region
ORDER BY
    net_revenue DESC;
```

O prompt lista todas as 16 tabelas dos dois esquemas como comandos CREATE TABLE, somando 827 tokens com as instruções e a pergunta. A linha que importa aqui é a de analytics.fct_orders. Ela tem uma coluna net_revenue_eur, uma coluna order_date_local, uma coluna region e uma coluna status.

O SQL que o modelo escreveu é o que muitos analistas escreveriam primeiro. Ele escolhe o mart em vez das tabelas brutas e de orders_legacy. Soma net_revenue_eur, e não o valor bruto. Filtra por order_date_local, de modo que cada pedido cai no dia comercial da sua região em vez do dia UTC. Agrupa por região e dá à coluna um nome adequado. Se você revisasse essa consulta em um pull request, talvez a aprovasse. A questão é se o número que ela retorna está certo, e nada nesta saída pode lhe dizer isso.

Regra prática: Trate o texto para SQL apenas com o esquema como a linha de base a superar, não como o produto. Execute-o uma vez no seu próprio armazém e guarde as respostas dele, porque elas mostram quais das suas definições o esquema não carrega. Grave cada resposta do modelo de que os seus testes dependem, fixada a um arquivo de modelo, a um hash de prompt e a uma amostragem fixa, para que uma falha encontrada possa ser reproduzida por outra pessoa.

Execute o SQL e confira o número

Última alteração na edição 2026.11.12

A consulta do modelo para março de 2026 parece correta, e ela roda. Uma consulta que falha é percebida quando alguém vê o erro; uma que roda e devolve um número plausível é a falha que importa, porque nada a marca como errada. A única forma de saber é comparar o resultado com uma resposta que alguém tenha verificado.

Uma pergunta de referência (golden) é uma pergunta com sua resposta verificada: o SQL dourado, escrito segundo a definição do responsável, o resultado dourado que esse SQL devolve e o tipo de resposta esperado. O SQL dourado é verificado executando-o, o que o capítulo 3 explica. O livro guarda suas perguntas douradas em examples/data/golden/questions.toml, e lib/golden.py as carrega. O SQL dourado para gq-002 segue a definição de receita líquida da loja, que é de responsabilidade da equipe financeira: receita em euros após descontos e antes dos impostos, de pedidos reais que não foram cancelados, no dia útil local do pedido.

Coloque a consulta do modelo ao lado da dourada, região por região, com os pedidos cancelados de cada região ao lado para conferir a diferença.

run-the-model-sql.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Run the SQL the model wrote for net revenue by region in March 2026, and check it against the golden result. The prose reads each region's model, golden and cancelled-orders lines, and the final match line."""from lib.golden import golden_result, load_golden, results_matchfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()question = next(q for q in load_golden() if q.question_id == "gq-002")   # gq-002: net revenue in each region in March 2026reply = RecordedModel("schema-only-sql").complete(schema_only_messages(describe_schema(con), question.question))model_answer = dict(run_sql(con, extract_sql(reply)).rows)   # the query returns (region, net revenue) rows, keyed here by regiongolden = dict(golden_result(con, question))# order_date_local is a date, so BETWEEN with March 31 includes all of March.cancelled = dict(con.execute("""    SELECT region, sum(net_revenue_eur) FROM analytics.fct_orders    WHERE status = 'cancelled' AND order_date_local BETWEEN DATE '2026-03-01' AND DATE '2026-03-31'    GROUP BY region""").fetchall())for region in sorted(golden):    print(f"{region} model: {model_answer[region]:,.2f}")    print(f"{region} golden: {golden[region]:,.2f}")    print(f"{region} cancelled orders: {cancelled[region]:,.2f}")print(f"model total: {sum(model_answer.values()):,.2f}")print(f"golden total: {sum(golden.values()):,.2f}")# as a share of the golden totalprint(f"overstated by: {sum(model_answer.values()) / sum(golden.values()) - 1:.1%}")matches = results_match(model_answer.items(), golden.items())assert not matches           # the model's SQL keeps cancelled orders, so its rows can't equal the golden rowsprint(f"matches golden: {'yes' if matches else 'no'}")
Saídapython run-the-model-sql.py
AMER model: 55,207.80
AMER golden: 51,762.14
AMER cancelled orders: 3,445.66
APAC model: 40,832.21
APAC golden: 35,296.93
APAC cancelled orders: 5,535.28
EMEA model: 66,502.78
EMEA golden: 63,023.76
EMEA cancelled orders: 3,479.02
model total: 162,542.79
golden total: 150,082.83
overstated by: 8.3%
matches golden: no

A consulta superestima a receita líquida exatamente pelos pedidos cancelados que ela conta. Para a EMEA, ela informa 66,502.78 euros contra um valor dourado de 63,023.76, e a diferença, 3,479.02, é a receita líquida dos pedidos cancelados da EMEA naquele mês. AMER e APAC seguem o mesmo padrão. Somando as três regiões, o total do modelo está 8.3% acima do total dourado.

A consulta não foi descuidada. O esquema mostra uma coluna status, mas nada nela diz que pedidos cancelados não entram na receita. Essa regra está na definição da equipe financeira, que um modelo que lê nomes de colunas não consegue ver. Um modelo maior talvez adivinhe a regra com mais frequência, mas adivinhar é o mecanismo errado: a pergunta seguinte pode depender de uma regra que ninguém adivinharia, como a qual dia pertence um reembolso.

Observe o que a verificação compara: as linhas, não o texto do SQL, e aqui as linhas não coincidem. results_match() em lib/golden.py, a regra que todas as pontuações deste livro usam, as rejeita, o que o exemplo comprova.

Regra prática: Nunca aceite o número de um agente só porque o SQL parece correto. Confira-o com um resultado dourado antes que alguém dependa dele e, quando os dois diferirem, encontre as linhas que explicam a diferença antes de alterar qualquer coisa. Espere que a diferença seja uma definição, como quais pedidos contam, com mais frequência do que um erro de sintaxe.

Esta parte ainda não foi traduzida, por isso está em inglês.

Answer from one defined metric

Última alteração na edição 2026.11.15

Counting cancelled orders broke the first number, because the rule that excludes them isn't in the schema. The fix this book recommends is to stop asking the model for SQL over tables, and to give it defined metrics instead. A metric is a business measure written down once, by the people who own it: a name, a description a person can check, one aggregate over one mart, the rule for which rows count, and the dimensions it may be grouped and filtered by. The model's job shrinks to choosing a metric and its arguments. Code that you wrote and tested turns that choice into SQL.

This chapter has one metric, net_revenue, in lib/metrics.py. Its rule for which rows count is the finance team's: status <> 'cancelled' on analytics.fct_orders. Its dimensions are region, channel, fiscal_year, fiscal_quarter, calendar_year and calendar_month, each mapped to one SQL expression. A metric request names the metric, the dimensions to group by and one value per filtered dimension, and compile_request() turns it into SQL. Dimension names come only from that list, and filter values are passed as query parameters, never pasted into the SQL text.

The model reaches the metric through tools. A tool is a function the model may ask the code to run, by replying with a JSON object that names it and gives its arguments. This agent has two, in lib/tools.py. query_metric computes a metric for a request. cannot_answer declines, with a one-sentence reason, when no metric covers the question. The loop that connects them is the book's own, run_agent() in lib/agent.py. It sends the messages, reads one tool call from the reply, runs the tool and stops when the tool returns an answer, after at most three model calls. The prompt, METRIC_TOOLS in lib/prompts.py, lists the metric's description and each dimension's meaning, including when the fiscal year starts. It lists no tables.

The recording metric-tool-runs holds the same model's replies to the metric prompt, recorded the way schema-only-sql was. Here is gq-002 again, through the metric.

one-metric-answer.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Answer the same question from one defined metric: the model picks the metric, the code writes and runs the SQL. The point rests on the request and the compiled SQL printed here, and on the assertion that the answer equals the golden result."""from lib.agent import run_agentfrom lib.golden import golden_result, load_golden, results_matchfrom lib.metrics import METRICS, NET_REVENUEfrom lib.model import RecordedModelfrom lib.prompts import metric_tools_promptfrom lib.tools import Toolboxfrom lib.warehouse import connectcon = connect()question = next(q for q in load_golden() if q.question_id == "gq-002")   # the same question the SQL examples answerprint(f"metric: {NET_REVENUE.name}")print(f"definition: {NET_REVENUE.description}")system = metric_tools_prompt(METRICS.values())trace = run_agent(question.question, system, RecordedModel("metric-tool-runs"), Toolbox(con))answer = trace.answer# the first step is the model's tool call, and its arguments are the request the code compilesprint(f"request: {trace.steps[0].arguments}")print(answer.provenance.sql)print(answer.show())print(answer.provenance.describe())matches = results_match(answer.rows, golden_result(con, question))assert matches               # the metric's rule drops cancelled orders, as the golden SQL doesprint(f"matches golden: {'yes' if matches else 'no'}")
Saídapython one-metric-answer.py
metric: net_revenue
definition: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local business day. Returned orders count; refunds are not subtracted.
request: {'metric': 'net_revenue', 'group_by': ['region'], 'filters': {'calendar_month': 3, 'calendar_year': 2026}}
SELECT o.region AS region, round(sum(o.net_revenue_eur), 2) AS net_revenue
FROM analytics.fct_orders AS o
JOIN analytics.dim_date AS d ON d.date_day = o.order_date_local
WHERE o.status <> 'cancelled' AND d.calendar_month = $1 AND d.calendar_year = $2
GROUP BY o.region
ORDER BY o.region
region  net_revenue
AMER    51,762.14
APAC    35,296.93
EMEA    63,023.76
source: metric (net_revenue)
filters: {'calendar_month': 3, 'calendar_year': 2026}
role: analyst
data as of: 2026-07-02 02:00:00
matches golden: yes

The model asked for net_revenue, grouped by region and filtered to calendar month 3 of calendar year 2026. The SQL the code compiled from that request applies the cancelled-orders rule, joins the date dimension on the local business day and passes the month and year as parameters. Each region matches its golden result.

The answer also carries its provenance: the metric that produced it, the filters, the role it was computed for, and how fresh the data is. The data as of line is when the newest row in fct_orders was loaded, read from its _loaded_at column. A person can see the definition and the currency of a number without reading SQL.

One metric is a long way from a semantic layer. It can't join through entities, it has one grain and it holds one definition. Chapter 5 replaces it with a semantic layer that does those things. The shape stays, though: the model chooses a governed definition, and code writes the SQL.

Working rule: Route a question to a defined metric before you let a model write SQL. Give the model the metric's description and its dimensions, and let it return a request, which your code validates and compiles. Write SQL from a model only for questions no metric covers, and only behind guards.

Esta parte ainda não foi traduzida, por isso está em inglês.

Score both on five golden questions

Última alteração na edição 2026.11.15

One question answered from the metric shows the approach can work. It doesn't show that it works more often than schema-only SQL. For that, score both on golden questions under the same comparison rule. A score on five questions is a smoke test, not a measurement, and it can't support a claim about this model, or about text-to-SQL in general. It still separates outcomes that one accuracy figure hides.

Each answer gets one of four outcomes. An answer is correct when the result matches the golden result, or when it declines a question that should be declined. A wrong answer returns a different result, or returns any result for a question that should be declined. An error is an answer whose SQL doesn't run. A declined answer says it can't answer a question that has an answer. A decline is not a wrong number, and a score that counts the two together hides the difference this book cares about most.

The comparison rule, results_match() in lib/golden.py, accepts an answer when it has as many rows as the golden result and its columns include every golden column's values. Columns are matched by their values, not their names, so column order doesn't matter, and neither do extra columns, such as a fiscal_year column beside the total. Row order doesn't matter unless the question says it does. Numbers must agree within 0.05 percent, or within half a cent. Chapter 3 discusses each of these choices.

The five golden questions cover the traps one at a time:

ID Question Kind
gq-001 Net revenue in fiscal year 2026 answer
gq-002 Net revenue in each region in March 2026 answer
gq-003 Net revenue by sales channel in calendar 2025 answer
gq-004 Customers whose first order was in fiscal 2026 answer
gq-005 Net revenue next quarter decline

Both approaches face all five, and the output has one row per question, showing where each one fails.

score-five-golden.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Score both approaches on five golden questions: schema-only SQL, and the agent with one defined metric. The prose's counts are the totals printed on the last lines, one per outcome and approach."""from collections import Counterimport duckdbfrom lib.agent import run_agentfrom lib.golden import golden_result, grade, load_goldenfrom lib.metrics import METRICSfrom lib.model import RecordedModelfrom lib.prompts import metric_tools_prompt, schema_only_messagesfrom lib.tools import Toolbox, extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()schema, system = describe_schema(con), metric_tools_prompt(METRICS.values())sql_model, metric_model = RecordedModel("schema-only-sql"), RecordedModel("metric-tool-runs")totals = {"schema-only": Counter(), "metric": Counter()}print("question  kind     schema-only  metric")for q in load_golden()[:5]:      # the first five; chapter 3 builds the full set    golden = golden_result(con, q)    try:        sql = extract_sql(sql_model.complete(schema_only_messages(schema, q.question)))        sql_outcome = grade(q, run_sql(con, sql), golden)    except duckdb.Error:         # a query that doesn't run raises a DuckDB error, which the score counts as an error        sql_outcome = "error"    metric_outcome = grade(q, run_agent(q.question, system, metric_model, Toolbox(con)).answer, golden)    totals["schema-only"][sql_outcome] += 1    totals["metric"][metric_outcome] += 1    print(f"{q.question_id}    {q.kind:<7}  {sql_outcome:<11}  {metric_outcome}")for name, counts in totals.items():    for outcome in ("correct", "wrong", "error", "declined"):        print(f"{name} {outcome}: {counts[outcome]} of {sum(counts.values())}")
Saídapython score-five-golden.py
question  kind     schema-only  metric
gq-001    answer   error        correct
gq-002    answer   wrong        correct
gq-003    answer   error        correct
gq-004    answer   wrong        declined
gq-005    decline  wrong        correct
schema-only correct: 0 of 5
schema-only wrong: 3 of 5
schema-only error: 2 of 5
schema-only declined: 0 of 5
metric correct: 4 of 5
metric wrong: 0 of 5
metric error: 0 of 5
metric declined: 1 of 5

Schema-only SQL gets 0 of 5 questions right, and the way it fails matters more than that count. It fails to run on 2 of 5 questions: for gq-001 and gq-003 the model filtered fct_orders on fiscal_year and calendar_year, columns that exist only in dim_date. Those failures are visible, which makes them the cheap ones. Its wrong answers, on 3 of 5 questions, are not. gq-002 counts cancelled orders. gq-004 counts customers whose first order fell in calendar 2026 instead of fiscal 2026. And gq-005, a forecast the warehouse can't make, gets a query over the quarter that contains today's date, which runs and returns a total instead of saying the question can't be answered.

The agent with one metric gets 4 of 5 questions right, including the decline for the forecast, and makes 0 of 5 wrong answers. It declines gq-004, which the warehouse can answer but net_revenue can't, since it counts revenue, not customers. That decline is the cost of the approach, and it is the right cost. A person who hears "I can't answer that from the metrics I have" knows to ask someone, while a person who hears a wrong count doesn't.

Small as it is, the score does show one thing. On this warehouse, the failures came from definitions the schema doesn't hold, and moving the definitions into code removed them. Chapter 3 builds the golden set to 48 questions, with a held-out split, and every later chapter reports its numbers on it.

Working rule: Score every change on golden questions written from your own work, and report correct, wrong, error and declined separately. Include questions that should be declined from the start, or an agent that never declines will look perfect. Use a handful of questions as a smoke test while you build, and a larger set with a held-out split before you claim anything.

Leia o rastreamento de uma execução

Última alteração na edição 2026.11.12

Uma pontuação mostra com que frequência o agente acertou. Um rastreamento mostra por quê, em uma única execução. O rastreamento é cada passo de uma execução, registrado por run_agent(): cada resposta do modelo e cada resultado de ferramenta devolvido. Ler rastreamentos mostra se um resultado correto foi correto pelo motivo certo, e no que se baseou uma recusa.

O agente recusou gq-004 na pontuação de cinco perguntas, então esta reprodução imprime cada passo dessa execução.

A recusa foi a decisão certa, mas o motivo é falso. A recusa está certa porque net_revenue não consegue contar clientes. O motivo diz que os dados não têm informação sobre o número de clientes que fizeram o primeiro pedido em um ano fiscal, enquanto analytics.dim_customers tem uma coluna first_order_on. A execução terminou com uma chamada a cannot_answer, um motivo em vez de um resultado, depois de 1 chamada de modelo ao todo. O modelo viu apenas a descrição da métrica e as dimensões, então afirmou coisas sobre dados que não podia ver. Um leitor concluiria que o armazém de dados não consegue responder à pergunta, o que não é verdade.

Regra prática: Leia rastreamentos, não apenas pontuações, e leia primeiro as recusas. Verifique se o motivo de cada recusa é sobre o que o agente recebeu, como “nenhuma métrica conta clientes”, e não uma afirmação sobre dados que ele nunca viu. Trate uma recusa com motivo falso como defeito, mesmo quando a pontuação a contabiliza como recusa correta.

O que dá errado em produção

Última alteração na edição 2026.11.12

O agente rudimentar construído aqui funciona com cinco perguntas. Estas são as formas como o desenho falha quando as pessoas passam a depender dele, e como você perceberia cada uma delas.

Um número plausível entra em uma decisão. SQL apenas com o schema que roda retorna um número sem nenhum aviso, como gq-002 mostrou com um total 8.3% acima do correto. Ninguém percebe até que alguém compare com o relatório da equipe financeira, muitas vezes semanas depois. O alerta antecipado é pontuar as perguntas de referência antes do lançamento e após cada mudança, e mostrar a proveniência com cada resposta, para que o leitor veja qual definição foi usada.

As definições se afastam da métrica. A descrição da métrica diz que pedidos cancelados não contam, e o SQL dela garante isso. Quando a equipe financeira muda uma regra, como excluir as taxas de um marketplace, a descrição, o SQL e o SQL de referência precisam receber a mesma mudança. Se um deles for esquecido, as respostas do agente e os resultados de referência se distanciam, e a pontuação cai. Essa queda é o alarme; por isso, mantenha as perguntas de referência no mesmo repositório das definições da métrica e revise as mudanças nos dois juntos.

O agente recusa por um motivo que não é verdadeiro. O trace de gq-004 recusou corretamente, mas afirmou que os dados não têm datas de primeiro pedido. Uma pessoa que acredita nesse motivo deixa de perguntar. Você percebe isso lendo as recusas nos traces e mantendo perguntas de referência que o warehouse consegue responder, mas as métricas não; assim, um motivo falso aparece como uma recusa em uma pergunta que você sabe que pode ser respondida.

Uma resposta do modelo muda sem que ninguém perceba. Se um exemplo chamasse um modelo ao vivo, uma nova versão do modelo ou um prompt alterado mudaria silenciosamente todos os números a jusante. A reprodução em lib/model.py busca as respostas gravadas pelo hash das mensagens exatas, então um prompt alterado para com MissingRecording. Grave de novo de propósito, e trate uma nova versão do modelo como um lançamento de biblioteca: grave, pontue e compare.

O template de chat do arquivo do modelo não é o do publicador. O arquivo quantizado com que este livro grava embute um template de chat diferente do que o Qwen publica para este modelo (template do Qwen). O template embutido adiciona um bloco de pensamento vazio a um turno do assistente que encerra a conversa, algo que o próprio template do Qwen não faz. Nosso runtime de gravação, recordings/local_model.py, renderiza cada prompt com o template do Qwen em uma revisão fixada, verificada por hash, e cada manifesto registra se o template embutido coincidiu. Comparar os dois antes da primeira gravação detecta o problema, e não uma série de respostas estranhas depois.

Dados desatualizados respondem com confiança. A resposta da métrica dizia quando a linha mais recente de fct_orders foi carregada. Um mart cuja carga parou continuaria respondendo, com dados antigos, a menos que algo compare essa data com o que a pergunta exige. Mostre a data com cada resposta, no mínimo, e recuse quando ela for antiga demais para a pergunta.

O SQL do modelo é executado sem verificações. Neste capítulo, run_sql() em lib/tools.py executa tudo o que o modelo escreveu. Aqui a conexão com o warehouse é somente leitura e não pode abrir outros arquivos, o que limita o dano à leitura. Uma conexão de warehouse de produção geralmente tem mais permissões do que essas. Nunca dê ao SQL de um modelo uma conexão que possa escrever: conecte-o em modo somente leitura a um banco que contenha apenas o que o papel de quem pergunta pode ler (capítulo 7), e adicione proteções na frente dela como defesa em profundidade.

Regra prática: Antes de qualquer pessoa fora da sua equipe usar o agente, torne visível cada uma das falhas acima: pontue as perguntas de referência no CI, mostre a proveniência e a atualidade dos dados com cada resposta, revise as recusas nos traces, reproduza as respostas gravadas pelo hash da mensagem, e execute o SQL escrito pelo modelo apenas em uma conexão somente leitura. Comece pela pontuação de referência, porque é a única dessas verificações que pega um número errado plausível.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.12
  • O caso recorrente do livro é uma loja que nós geramos. O data warehouse da loja é gerado a partir de uma única semente, com as armadilhas que um data warehouse real tem, de modo que todo leitor obtém as mesmas linhas e nada depende de dados privados.
  • O data warehouse é somente leitura. warehouse.connect() retorna uma conexão que não pode escrever nem abrir outros arquivos, de modo que até mesmo SQL não verificado só pode ler.
  • A linha de base é registrada de fato. As respostas do SQL somente com esquema vêm do modelo fixado acima, com a amostragem recomendada pelo Qwen e uma redefinição da semente antes de cada chamada.
  • Toda resposta do modelo é registrada e reproduzida pelo hash da mensagem. Um prompt alterado falha de forma explícita, em vez de reutilizar uma resposta antiga.
  • As métricas vêm antes do SQL. O modelo escolhe uma métrica definida e seus argumentos; o código valida a solicitação e escreve o SQL.
  • Recusar é uma resposta. O agente tem uma ferramenta cannot_answer, e as pontuações contam as recusas separadamente dos erros.
  • Uma única comparação pontua tudo: linhas são comparadas, não o texto do SQL, pela mesma regra em todas as vezes: as mesmas linhas, todas as colunas do gabarito presentes, em qualquer ordem, com uma pequena tolerância.
  • O laço é nosso, não de um framework. São algumas dezenas de linhas em lib/agent.py que uma nova versão de biblioteca não consegue alterar. O desenvolvimento de um framework pode parar: o vanna, um framework de código aberto de texto para SQL, foi arquivado por seus mantenedores em 29 de março de 2026 (repositório).

Este capítulo, nesta edição

Edição 2026.11.15Exemplos aprovados em 19 de nov de 20266 de 6 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.15.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 1 de 11: Um agente de dados de ponta a ponta

  1. Meet the shop and its warehouse
  2. Faça uma pergunta e receba SQL de um modelo
  3. Execute o SQL e confira o número
  4. Answer from one defined metric
  5. Score both on five golden questions
  6. Leia o rastreamento de uma execução
  7. O que dá errado em produção
  8. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos