Un agente de datos de principio a fin
Unos 24 minutos de lectura, con 6 ejemplos en 8 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.15. Lee el original
Al final de este capítulo, serás capaz de construir el almacén de datos de la tienda, pedir a un modelo de lenguaje grabado que escriba SQL para una pregunta de negocio, ejecutar ese SQL y detectar el número incorrecto que devuelve, responder la misma pregunta a partir de una única métrica definida, y evaluar ambos enfoques con cinco preguntas doradas. Es el resultado completo de este libro en versión preliminar: cada capítulo posterior vuelve sólida una parte de él.
La petición que responde este libro suele llegar en una sola frase: que la gente pueda preguntar a los datos. Alguien de finanzas quiere los ingresos netos por región del mes pasado sin esperar a un panel, y alguien te entrega un modelo de lenguaje. La solución evidente le da al modelo el esquema del almacén y la pregunta, ejecuta el SQL que escribe y muestra el resultado. En una pregunta escogida a mano, esa solución a menudo funciona, lo cual basta para una demostración; en las cinco preguntas doradas de este libro acierta 0 of 5 de ellas. Sus fallos son el problema, porque la mayoría no parecen fallos. Una consulta que no se ejecuta es un error que alguien ve. Una consulta que se ejecuta y devuelve un número unos puntos porcentuales demasiado alto acaba en una diapositiva.
Este capítulo construye primero la versión evidente, la ejecuta y muestra exactamente dónde se equivoca su número. Después construye la versión más pequeña de la alternativa que recomienda el libro: un agente que no ve tablas en absoluto, solo una métrica definida, y que indica cuándo la métrica no cubre una pregunta. Ambas se evalúan con las mismas cinco preguntas, con respuestas verificadas, el hábito del que depende el resto del libro.
Necesitas Python 3.12.15 y SQL, y nada más: ni GPU, ni cuenta en la nube, ni clave de API. Cada ejemplo se ejecuta sin conexión sobre duckdb 2.0.0, con datos que el libro genera, y cada respuesta del modelo que utiliza fue grabada una vez a partir de un modelo abierto y se reproduce desde un archivo.
Esta parte aún no está traducida, así que está en inglés.
Meet the shop and its warehouse
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.
1"""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."""2from lib.shop_data import SHOP_SEED3from lib.warehouse import connect, table_sizes45con = connect() # generates the shop, loads raw, builds the marts, reopens read-only6print(f"seed: {SHOP_SEED}")7for table, rows in table_sizes(con):8 print(f"{table}: {rows:,}")910# The trailing comma unpacks the one row this query returns. order_date_local is the order's day in its11# region's time zone, the day sales are counted on; is_test marks orders placed from the shop's test accounts.12(first, last, test_orders, cancelled), = con.execute("""13 SELECT (SELECT min(order_date_local) FROM analytics.fct_orders),14 (SELECT max(order_date_local) FROM analytics.fct_orders),15 (SELECT count(*) FROM raw.orders WHERE is_test),16 (SELECT count(*) FROM analytics.fct_orders WHERE status = 'cancelled')17""").fetchall()18print(f"first order day: {first}")19print(f"last order day: {last}")20print(f"test orders in raw.orders: {test_orders}")21print(f"cancelled orders in fct_orders: {cancelled}")
python load-the-warehouse.pyseed: 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.
Haz una pregunta y obtén SQL de un modelo
Con el almacén de datos de la tienda ya construido, el siguiente paso evidente es dejar que un modelo lo consulte. El text-to-SQL solo con el esquema consiste en darle al modelo el nombre y el tipo de cada columna y la pregunta de la persona, y nada más, para que escriba el SQL. Según nuestra experiencia, aquí empiezan muchas de las primeras versiones, porque el esquema es la única descripción del almacén que existe, y la base de datos la mantiene al día. Lo que deja fuera son las definiciones, que el esquema no contiene.
Un libro cuyos ejemplos llamaran a un modelo daría una respuesta distinta en cada ejecución y necesitaría una clave de API. Por eso, cada respuesta del modelo en este libro está grabada. Una grabación es un conjunto guardado de respuestas del modelo, con un manifiesto, creado una sola vez por un script en la carpeta recordings/ del repositorio y reproducido por los ejemplos. El modelo es Qwen3-4B-Instruct-2507, que Qwen publica con la licencia Apache 2.0. Tiene 4.0 mil millones de parámetros y responde sin una fase de razonamiento aparte, así que la respuesta contiene únicamente el resultado (la tarjeta del modelo de Qwen). Usamos una cuantización de 4 bits de este modelo, un archivo de unos 2.5 GB fijado por su hash SHA-256 (el archivo), con cuatro hilos de CPU mediante llama-cpp-python, para que cualquiera pueda volver a grabarlo sin una GPU.
Los ajustes de muestreo son los que Qwen recomienda para este modelo: temperatura 0.7, top-p 0.8, top-k 20 y min-p 0 (la tarjeta del modelo de Qwen). La semilla se reinicia antes de cada llamada. Las respuestas se limitan a 384 tokens para SQL y a 256 para el resto. Ese límite es decisión nuestra, para que una grabación en CPU sea corta, aunque Qwen sugiere 16,384. El manifest.json de cada grabación indica el script, el modelo y el hash de su archivo, el hash del prompt, el muestreo, la fecha y el tiempo de cada llamada.
Del lado de los ejemplos, lib/model.py proporciona RecordedModel("schema-only-sql"), que reproduce esa grabación. Busca cada respuesta por el SHA-256 de los mensajes exactos enviados. Un prompt que difiera en un solo carácter no tiene grabación, y la reproducción se detiene con un error en lugar de devolver una respuesta destinada a otro prompt. El prompt en sí es una constante en lib/prompts.py, SCHEMA_ONLY_SQL, compartida por el script de grabación y los ejemplos.
La pregunta es una que el equipo de finanzas formula cada mes: "¿Cuál fue el ingreso neto de cada región en marzo de 2026?" También es gq-002, una pregunta de referencia con una respuesta verificada; la siguiente sección comprueba la respuesta frente a ella. Antes de juzgar su número, lee el SQL que escribe el modelo.
1"""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."""2from lib.golden import load_golden3from lib.model import RecordedModel4from lib.prompts import schema_only_messages5from lib.warehouse import connect, describe_schema67schema = describe_schema(connect())8# gq-002 is net revenue in each region in March 2026, the question the prose follows.9question = next(q for q in load_golden() if q.question_id == "gq-002")10messages = schema_only_messages(schema, question.question)1112# Each table's schema is one CREATE TABLE statement, so counting them counts the tables.13print(f"tables in the prompt: {schema.count('CREATE TABLE')}")14# The trailing space makes this match the whole table name, not a longer one that starts the same way.15print(next(line for line in schema.splitlines() if "analytics.fct_orders " in line))1617model = RecordedModel("schema-only-sql") # replays the pinned model's real replies18call = model.call_for(messages)19print(f"prompt tokens: {call['prompt_tokens']}")20print(f"question: {question.question}")21print(call["reply"])
python first-question-to-sql.pytables 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;
```
El prompt enumera las 16 tablas de ambos esquemas como sentencias CREATE TABLE, 827 tokens con las instrucciones y la pregunta. La línea que importa aquí es la de analytics.fct_orders. Tiene una columna net_revenue_eur, una columna order_date_local, una region y una status.
El SQL que escribió el modelo es el que muchos analistas escribirían primero. Elige el data mart en lugar de las tablas en bruto y de orders_legacy. Suma net_revenue_eur, no el bruto. Filtra por order_date_local, así que cada pedido cae en el día natural local de su región en lugar de en su día UTC. Agrupa por región y da a la columna un nombre razonable. Si revisaras esta consulta en una solicitud de cambios, podrías aprobarla. La cuestión es si el número que devuelve es correcto, y nada en esta salida puede decírtelo.
Regla práctica: Trata el text-to-SQL solo con el esquema como la referencia que hay que superar, no como el producto. Ejecútalo una vez sobre tu propio almacén de datos y guarda sus respuestas, porque te muestra qué definiciones tuyas no recoge el esquema. Graba cada respuesta del modelo de la que dependan tus pruebas, fijada a un archivo de modelo, a un hash del prompt y a un muestreo fijo, para que alguien más pueda reproducir un fallo que encuentres.
Ejecuta el SQL y comprueba el número
La consulta del modelo para marzo de 2026 parece correcto, y se ejecuta. Una consulta que falla se detecta cuando alguien ve el error; una que se ejecuta y devuelve un número verosímil es el fallo que importa, porque nada la marca como incorrecta. La única forma de saberlo es comparar el resultado con una respuesta que alguien haya verificado.
Una pregunta dorada es una pregunta con su respuesta verificada: el SQL dorado, escrito según la definición del responsable, el resultado dorado que devuelve ese SQL y el tipo de respuesta esperada. El SQL dorado se verifica ejecutándolo, lo que cubre el capítulo 3. El libro guarda sus preguntas doradas en examples/data/golden/questions.toml, y lib/golden.py las carga. El SQL dorado para gq-002 sigue la definición de ingresos netos de la tienda, que es responsabilidad del equipo de finanzas: ingresos en euros después de descuentos y antes de impuestos, de pedidos reales que no fueron cancelados, en el día hábil local del pedido.
Coloca la consulta del modelo junto a la dorada, región por región, con los pedidos cancelados de cada región al lado para contrastar la diferencia.
1"""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."""2from lib.golden import golden_result, load_golden, results_match3from lib.model import RecordedModel4from lib.prompts import schema_only_messages5from lib.tools import extract_sql, run_sql6from lib.warehouse import connect, describe_schema78con = connect()9question = next(q for q in load_golden() if q.question_id == "gq-002") # gq-002: net revenue in each region in March 202610reply = RecordedModel("schema-only-sql").complete(schema_only_messages(describe_schema(con), question.question))1112model_answer = dict(run_sql(con, extract_sql(reply)).rows) # the query returns (region, net revenue) rows, keyed here by region13golden = dict(golden_result(con, question))14# order_date_local is a date, so BETWEEN with March 31 includes all of March.15cancelled = dict(con.execute("""16 SELECT region, sum(net_revenue_eur) FROM analytics.fct_orders17 WHERE status = 'cancelled' AND order_date_local BETWEEN DATE '2026-03-01' AND DATE '2026-03-31'18 GROUP BY region""").fetchall())1920for region in sorted(golden):21 print(f"{region} model: {model_answer[region]:,.2f}")22 print(f"{region} golden: {golden[region]:,.2f}")23 print(f"{region} cancelled orders: {cancelled[region]:,.2f}")24print(f"model total: {sum(model_answer.values()):,.2f}")25print(f"golden total: {sum(golden.values()):,.2f}")26# as a share of the golden total27print(f"overstated by: {sum(model_answer.values()) / sum(golden.values()) - 1:.1%}")28matches = results_match(model_answer.items(), golden.items())29assert not matches # the model's SQL keeps cancelled orders, so its rows can't equal the golden rows30print(f"matches golden: {'yes' if matches else 'no'}")
python run-the-model-sql.pyAMER 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
La consulta sobrestima los ingresos netos exactamente por los pedidos cancelados que cuenta. Para EMEA informa 66,502.78 euros frente a un valor dorado de 63,023.76, y la diferencia, 3,479.02, es el ingreso neto de los pedidos cancelados de EMEA ese mes. AMER y APAC siguen el mismo patrón. En las tres regiones, el total del modelo está 8.3% por encima del total dorado.
La consulta no fue descuidada. El esquema muestra una columna status, pero nada en ella indica que los pedidos cancelados no cuentan para los ingresos. Esa regla está en la definición del equipo de finanzas, que un modelo que lee nombres de columnas no puede ver. Un modelo más grande podría adivinar la regla más a menudo, pero una suposición es el mecanismo equivocado: la siguiente pregunta puede depender de una regla que nadie adivinaría, como a qué día pertenece una devolución.
Fíjate en lo que compara la comprobación: las filas, no el texto del SQL, y aquí las filas no coinciden. results_match() en lib/golden.py, la regla que usa toda puntuación de este libro, las rechaza, como lo comprueba el ejemplo.
Regla práctica: Nunca aceptes el número de un agente porque su SQL parezca correcto. Compáralo con un resultado dorado antes de que alguien dependa de él, y cuando los dos difieran, busca las filas que explican la diferencia antes de cambiar nada. Espera que la diferencia sea una definición, como qué pedidos cuentan, con más frecuencia que un error de sintaxis.
Esta parte aún no está traducida, así que está en inglés.
Answer from one defined metric
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.
1"""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."""2from lib.agent import run_agent3from lib.golden import golden_result, load_golden, results_match4from lib.metrics import METRICS, NET_REVENUE5from lib.model import RecordedModel6from lib.prompts import metric_tools_prompt7from lib.tools import Toolbox8from lib.warehouse import connect910con = connect()11question = next(q for q in load_golden() if q.question_id == "gq-002") # the same question the SQL examples answer12print(f"metric: {NET_REVENUE.name}")13print(f"definition: {NET_REVENUE.description}")1415system = metric_tools_prompt(METRICS.values())16trace = run_agent(question.question, system, RecordedModel("metric-tool-runs"), Toolbox(con))17answer = trace.answer18# the first step is the model's tool call, and its arguments are the request the code compiles19print(f"request: {trace.steps[0].arguments}")20print(answer.provenance.sql)21print(answer.show())22print(answer.provenance.describe())23matches = results_match(answer.rows, golden_result(con, question))24assert matches # the metric's rule drops cancelled orders, as the golden SQL does25print(f"matches golden: {'yes' if matches else 'no'}")
python one-metric-answer.pymetric: 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 aún no está traducida, así que está en inglés.
Score both on five golden questions
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.
1"""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."""2from collections import Counter34import duckdb5from lib.agent import run_agent6from lib.golden import golden_result, grade, load_golden7from lib.metrics import METRICS8from lib.model import RecordedModel9from lib.prompts import metric_tools_prompt, schema_only_messages10from lib.tools import Toolbox, extract_sql, run_sql11from lib.warehouse import connect, describe_schema1213con = connect()14schema, system = describe_schema(con), metric_tools_prompt(METRICS.values())15sql_model, metric_model = RecordedModel("schema-only-sql"), RecordedModel("metric-tool-runs")16totals = {"schema-only": Counter(), "metric": Counter()}1718print("question kind schema-only metric")19for q in load_golden()[:5]: # the first five; chapter 3 builds the full set20 golden = golden_result(con, q)21 try:22 sql = extract_sql(sql_model.complete(schema_only_messages(schema, q.question)))23 sql_outcome = grade(q, run_sql(con, sql), golden)24 except duckdb.Error: # a query that doesn't run raises a DuckDB error, which the score counts as an error25 sql_outcome = "error"26 metric_outcome = grade(q, run_agent(q.question, system, metric_model, Toolbox(con)).answer, golden)27 totals["schema-only"][sql_outcome] += 128 totals["metric"][metric_outcome] += 129 print(f"{q.question_id} {q.kind:<7} {sql_outcome:<11} {metric_outcome}")3031for name, counts in totals.items():32 for outcome in ("correct", "wrong", "error", "declined"):33 print(f"{name} {outcome}: {counts[outcome]} of {sum(counts.values())}")
python score-five-golden.pyquestion 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.
Lee la traza de una ejecución
Una puntuación indica con qué frecuencia el agente acertó. Una traza indica por qué, para una ejecución concreta. La traza es cada paso de una ejecución, registrado por run_agent(): cada respuesta del modelo y cada resultado de herramienta devuelto. Leer las trazas muestra si un resultado correcto lo fue por la razón adecuada, y en qué se basó una negativa.
El agente declinó responder gq-004 en la puntuación de cinco preguntas, así que esta reproducción imprime cada paso de esa ejecución.
1"""Print the trace of one recorded agent run: every model reply and tool result, then what the run returned. The `reason:` line printed last settles whether the decline's stated cause is true."""2from lib.agent import run_agent3from lib.golden import load_golden4from lib.metrics import METRICS5from lib.model import RecordedModel6from lib.prompts import metric_tools_prompt7from lib.tools import Toolbox8from lib.warehouse import connect910con = connect()11# gq-004: customers whose first order fell in fiscal 2026, which net_revenue can't count12question = next(q for q in load_golden() if q.question_id == "gq-004")13system = metric_tools_prompt(METRICS.values())14trace = run_agent(question.question, system, RecordedModel("metric-tool-runs"), Toolbox(con))1516print(trace.show())17# each step is either a model reply or a tool result; this counts the replies18print(f"model calls: {sum(step.kind == 'model' for step in trace.steps)}")19print(f"answered: {trace.answer.answered}")20print(f"reason: {trace.answer.reason}")
python print-one-trace.pyquestion: How many customers placed their first order in fiscal year 2026?
step 1 (model):
{"tool": "cannot_answer", "arguments": {"reason": "The data does not include information about the number of customers who placed their first order in a fiscal year."}}
step 2 (tool):
declined: The data does not include information about the number of customers who placed their first order in a fiscal year.
model calls: 1
answered: False
reason: The data does not include information about the number of customers who placed their first order in a fiscal year.
La negativa fue la decisión correcta, pero su motivo es falso. Rechazar es correcto porque net_revenue no puede contar clientes. El motivo dice que los datos no tienen información sobre el número de clientes que hicieron su primer pedido en un año fiscal, mientras que analytics.dim_customers tiene una columna first_order_on. La ejecución terminó con una llamada a cannot_answer, un motivo en lugar de un resultado, tras 1 llamada al modelo en total. El modelo solo vio la descripción de la métrica y sus dimensiones, así que afirmó cosas sobre datos que no podía ver. Un lector concluiría que el almacén de datos no puede responder a la pregunta, lo cual no es cierto.
Regla práctica: Lee las trazas, no solo las puntuaciones, y lee primero las negativas. Comprueba que el motivo de cada negativa trate sobre lo que se le dio al agente, como "ninguna métrica cuenta clientes", y no a una afirmación sobre datos que nunca vio. Considera un defecto una negativa con un motivo falso, aunque la puntuación la cuente como rechazada.
Qué sale mal en producción
El agente improvisado que se construye aquí responde cinco preguntas. Estos son los puntos en los que el diseño falla cuando la gente depende de él, y cómo podrías darte cuenta de cada uno.
Un número plausible entra en una decisión. El SQL que solo usa el esquema y se ejecuta devuelve un número sin ninguna advertencia, como gq-002 mostró con un total 8.3% demasiado alto. Nadie lo nota hasta que alguien lo compara con el informe del equipo de finanzas, a menudo semanas después. La alerta temprana consiste en evaluar con preguntas de referencia antes de cada publicación y después de cada cambio, y en mostrar la procedencia con cada respuesta, para que el lector vea qué definición se usó.
Las definiciones se desvían de la métrica. La descripción de la métrica dice que los pedidos cancelados no cuentan, y su SQL lo aplica. Cuando el equipo de finanzas cambia una regla, por ejemplo al excluir las comisiones de un marketplace, la descripción, el SQL y el SQL de referencia necesitan el mismo cambio. Si se olvida uno, las respuestas del agente y los resultados de referencia se separan, y la puntuación baja. Esa caída es la alarma, así que guarda las preguntas de referencia en el mismo repositorio que las definiciones de la métrica y revisa los cambios en ambas a la vez.
El agente se niega por un motivo que no es cierto. La traza de gq-004 se negó correctamente, pero afirmó que los datos no tienen fechas del primer pedido. Una persona que cree ese motivo deja de preguntar. Lo detectas leyendo las negativas en las trazas, y manteniendo preguntas de referencia que el almacén puede responder pero las métricas no, de modo que un motivo falso aparezca como una negativa en una pregunta que sabes que sí tiene respuesta.
La respuesta de un modelo cambia sin que nadie lo note. Si un ejemplo llamara a un modelo en directo, una nueva versión del modelo o un prompt modificado cambiaría en silencio cada número posterior. La reproducción en lib/model.py busca las respuestas por el hash de los mensajes exactos, así que un prompt cambiado se detiene con MissingRecording. Vuelve a grabar de forma deliberada, y trata una nueva versión del modelo como una versión de biblioteca: graba, evalúa y compara.
La plantilla de chat del archivo del modelo no es la del editor. El archivo cuantizado con el que este libro graba incluye una plantilla de chat distinta a la que Qwen publica para este modelo (la plantilla de Qwen). La incluida añade un bloque de pensamiento vacío a un turno del asistente que termina la conversación, algo que la propia plantilla de Qwen no hace. Nuestro entorno de grabación, recordings/local_model.py, genera cada prompt con la plantilla de Qwen en una revisión fijada, verificada por hash, y cada manifiesto registra si la plantilla incluida coincidía. Comparar ambas antes de la primera grabación detecta el problema, no una serie de respuestas extrañas después.
Los datos desactualizados responden con seguridad. La respuesta de la métrica indicaba cuándo se cargó la fila más reciente de fct_orders, y esa fecha puede quedarse atrás. Un mart cuya carga se detuvo seguiría respondiendo, con datos antiguos, a menos que algo compare esa fecha con lo que necesita la pregunta. Muestra al menos la fecha con cada respuesta, y niégate a responder cuando sea demasiado antigua para la pregunta.
El SQL del modelo se ejecuta sin controles. En este capítulo, run_sql() en lib/tools.py ejecuta todo lo que escribió el modelo. Aquí la conexión al almacén es de solo lectura y no puede abrir otros archivos, lo que limita el daño a la lectura. Una conexión de producción suele tener más permisos que eso. Nunca des al SQL de un modelo una conexión que pueda escribir: conéctalo en modo de solo lectura a una base de datos que contenga solo lo que el rol de quien pregunta puede leer (capítulo 7), y añade controles delante como defensa en profundidad.
Regla práctica: Antes de que alguien ajeno a tu equipo use el agente, haz visible cada uno de los fallos anteriores: evalúa con preguntas de referencia en CI, muestra la procedencia y la actualidad de los datos con cada respuesta, revisa las negativas en las trazas, reproduce las respuestas grabadas por el hash de los mensajes y ejecuta el SQL escrito por el modelo solo en una conexión de solo lectura. Empieza por la evaluación con preguntas de referencia, porque es la única de estas comprobaciones que detecta un número incorrecto pero plausible.
Decisiones que tomó este capítulo
- El caso de referencia del libro es una tienda que generamos. El almacén de la tienda se genera a partir de una única semilla, con las mismas trampas que tiene un almacén real, de modo que cada lector obtiene las mismas filas y nada depende de datos privados.
- El almacén es de solo lectura.
warehouse.connect()devuelve una conexión que no puede escribir ni abrir otros archivos, así que incluso el SQL sin verificar solo puede leer. - La línea base se registra realmente, no se simula. Las respuestas del SQL solo con esquema provienen del modelo fijado arriba, con el muestreo recomendado por Qwen y una semilla reiniciada antes de cada llamada.
- Cada respuesta del modelo se registra y se reproduce mediante su hash de mensaje. Si un prompt cambia, la reproducción falla de forma explícita en lugar de reutilizar una respuesta antigua.
- Las métricas van antes que el SQL. El modelo elige una métrica definida y sus argumentos; el código valida la solicitud y escribe el SQL.
- Declinar también es una respuesta. El agente dispone de una herramienta
cannot_answer, y las puntuaciones cuentan por separado las respuestas declinadas y las incorrectas. - Una única comparación puntúa todo: se comparan las filas, no el texto del SQL, con la misma regla en todos los casos: las mismas filas, todas las columnas del resultado de referencia presentes, en cualquier orden y con una pequeña tolerancia.
- El bucle es nuestro, no de un framework. Son unas pocas docenas de líneas en
lib/agent.pyque una nueva versión de una biblioteca no puede modificar. El desarrollo de un framework puede detenerse: vanna, un framework de código abierto de texto a SQL, fue archivado por sus mantenedores el 29 de marzo de 2026 (repositorio).
Este capítulo, en esta edición
Edición 2026.11.15Ejemplos verificados el 19 de nov de 2026Superan la prueba 6 de 6 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.15.