Encaminhe as perguntas primeiro para métricas governadas

Cerca de 34 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ê poderá oferecer ao agente as métricas da camada semântica como ferramentas, em vez das tabelas do armazém; fazer com que ele devolva uma requisição de métrica estruturada, validada antes de qualquer execução; fazer com que ele pergunte de volta à pessoa quando uma pergunta puder se referir a várias métricas; e medir a mudança nas perguntas de referência.

Capítulo 5 registrou as definições da loja uma única vez, como uma camada semântica: dez métricas sobre cinco modelos semânticos, compiladas para SQL pelo compilador do próprio livro em lib/semantic.py. Uma pessoa que conhece a camada pode pedir a ela a receita líquida por região em março de 2026 e obter o número da equipe financeira. O agente ainda não consegue. Capítulo 1 deu a ele uma única métrica, e a linha de base que ele precisa superar é o SQL baseado apenas no esquema, que acerta 2 of 24 perguntas de desenvolvimento. Capítulo 4 deu ao modelo as definições em texto ao lado do esquema, mas o modelo ainda escrevia o SQL, de modo que cada definição precisava sobreviver à sua leitura.

Quando o modelo escreve a consulta, qualquer definição que ele interpretar mal acaba no número. Encaminhar uma pergunta primeiro para métricas governadas exige tirar do modelo a tarefa de escrever a consulta: o trabalho dele passa a ser escolher qual métrica, agrupada por quê e filtrada como, e a camada, que as pessoas mantêm e testam, escreve o SQL. Fornecedores de armazéns descrevem seus próprios assistentes da mesma forma. A orientação da Databricks para os seus Genie Agents, que respondem perguntas, diz que as metric views funcionam especialmente bem com eles porque pré-definem métricas, dimensões e agregações (Databricks), e a Snowflake recomenda semantic views para o Cortex Analyst (Snowflake). Assim como as orientações dos fornecedores do capítulo 4, essas são recomendações, não medições. Este capítulo mede o padrão nas perguntas de referência da loja, com o mesmo modelo gravado usado em todos os outros capítulos.

Dê ao agente métricas, não tabelas

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

As ferramentas de um agente decidem o que ele pode errar. Quando recebe tabelas, um modelo pode fazer o join entre elas do jeito errado, deixar passar um filtro ou escolher a tabela legada, como o capítulo 2 mostrou uma falha de cada vez. Quando recebe métricas, ele ainda pode escolher a métrica errada ou a dimensão errada, mas não consegue reescrever uma definição, porque definições não estão entre as coisas que ele pode alterar. Uma ferramenta de métricas expõe o que uma camada semântica guarda, na forma em que uma pessoa a consulta: nomes de métricas com suas descrições, as dimensões pelas quais cada uma pode ser agrupada e filtrada, e as granularidades temporais. A Databricks descreve suas metric views do Unity Catalog nos mesmos termos, como uma forma de separar "definições de medidas dos campos (também chamados de dimensões) usados para agrupar, filtrar e agregar" (Databricks).

O agente da loja recebe suas ferramentas de métricas de lib/metric_tools.py, um módulo que este capítulo acrescenta. Sua MetricToolbox encapsula uma conexão com o data warehouse e a camada semântica do capítulo 5, e oferece cinco ferramentas: list_metrics, describe_metric, query_metric, ask_back e cannot_answer. O prompt, METRICS_FIRST em lib/prompts.py, traz o que list_metrics retorna, para que o modelo não gaste uma chamada pedindo essa informação: uma linha por métrica, com sua descrição e as dimensões que ela pode usar. O prompt também diz como o ano fiscal da loja funciona e como escrever um período como valor de filtro, e nomeia as regiões e os canais de venda. Ele não lista tabelas nem colunas.

Veja primeiro o que o agente enxerga. O exemplo monta o prompt e imprime a linha da receita líquida no catálogo, depois chama describe_metric para a taxa de devolução, e dimensiona uma pergunta de referência, gq-002, receita líquida por região em março de 2026, sob o prompt somente com esquema do capítulo 1 e sob este. Os dois tamanhos são as contagens de tokens que o runtime do modelo informou quando as chamadas foram registradas.

metric-tools.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Give the agent the semantic layer's metrics instead of the warehouse's tables, and compare what each prompt holds.The prose rests on the metric and table counts and the two prompt token counts, which come from the recordings."""from lib.golden import load_goldenfrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_prompt, schema_only_messagesfrom lib.warehouse import connect, describe_schemacon = connect()toolbox = MetricToolbox(con)system = metrics_first_prompt(catalog(toolbox.layer))print(f"tools: {', '.join(toolbox.tools)}")print(f"metrics in the prompt: {len(toolbox.layer.metrics)}")print(f"tables in the prompt: {system.count('CREATE TABLE')}")       # a table in the prompt would be written as a CREATE TABLE statementprint(catalog(toolbox.layer).splitlines()[0])                          # the first line: net revenue, with its dimensionsprint(toolbox.call("describe_metric", {"metric": "refund_rate"}).content)# The first call of the same golden question, gq-002, under each prompt, as the recordings measured it.question = next(q for q in load_golden() if q.question_id == "gq-002").questionschema_only = schema_only_messages(describe_schema(con), question)metrics_first = [{"role": "system", "content": system}, {"role": "user", "content": question}]print(f"schema-only prompt tokens: {RecordedModel('schema-only-sql').call_for(schema_only)['prompt_tokens']}")print(f"metrics-first prompt tokens: {RecordedModel('metric-agent-runs').call_for(metrics_first)['prompt_tokens']}")
Saídapython metric-tools.py
tools: list_metrics, describe_metric, query_metric, ask_back, cannot_answer
metrics in the prompt: 10
tables in the prompt: 0
- net_revenue: 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. Dimensions: customer__country, customer__first_order_date, customer__region, order__channel, order__country, order__order_date, order__region, order__status
refund_rate, a ratio metric: Refunded EUR over gross revenue of the same orders: orders placed in the period that weren't cancelled.
Dimensions:
- metric_time__day
- metric_time__week
- metric_time__month
- metric_time__quarter
- metric_time__year
- metric_time__fiscal_year: 2025, 2026, 2027
- metric_time__fiscal_quarter: 2025-Q1, 2025-Q2, 2025-Q3, 2025-Q4, 2026-Q1, 2026-Q2, 2026-Q3, 2026-Q4, 2027-Q1, 2027-Q2
- order__channel: (none), app, marketplace, web
- order__country: AU, CA, DE, ES, FR, GB, JP, NL, SG, US
- order__order_date
- order__region: AMER, APAC, EMEA
- order__status: cancelled, delivered, placed, returned, shipped
schema-only prompt tokens: 827
metrics-first prompt tokens: 1120

O prompt lista 10 métricas e 0 tabelas. Cada linha de métrica é a descrição do dono, palavra por palavra do YAML, seguida pelas dimensões que ela alcança sem fan-out. A linha da receita líquida cita order__region e customer__region, mas não product__category, porque o modelo de pedidos chega aos produtos somente pelos itens do pedido, várias por pedido.

describe_metric acrescenta o que o catálogo deixa de fora: as granularidades temporais e os valores de cada dimensão categórica, lidos do data warehouse quando a ferramenta roda. As regiões da taxa de devolução são AMER, APAC e EMEA, e seus trimestres fiscais são rótulos como 2026-Q1. O prompt já nomeia as regiões e os canais, então, para eles, a ferramenta apenas repete o que o modelo recebeu. Para os países, os status dos pedidos e os períodos fiscais, é o único lugar onde o modelo vê como a loja os escreve.

O prompt orientado a métricas não é menor. Ele tem 1120 tokens contra os 827 do prompt somente com esquema, porque uma definição usa mais palavras do que um nome de coluna. O que mudou é o que os tokens carregam: regras que uma pessoa escreveu e verificou, em vez de nomes que o modelo precisa interpretar.

Regra prática: Dê ao agente as métricas, suas descrições e as dimensões que cada uma pode usar, e mantenha as tabelas fora de suas ferramentas até que uma pergunta precise delas. Coloque o catálogo no prompt enquanto ele couber, para que uma execução não gaste uma chamada listando métricas, e deixe uma ferramenta de descrição retornar os valores das dimensões a partir do data warehouse. Quando o catálogo ultrapassar o prompt, mantenha os nomes e as descrições ali e mova as dimensões para trás da ferramenta de descrição.

Peça uma requisição, não SQL

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

Com as ferramentas de métricas no lugar, a resposta do modelo deixa de ser uma consulta e passa a ser uma requisição. Uma resposta estruturada é aquela que o código consegue analisar e transformar em um objeto tipado, verificando campo por campo. Aqui, ela é uma chamada de ferramenta em JSON cujos argumentos se tornam um MetricRequest, a requisição de métrica do capítulo 5, que nomeia métricas, dimensões de agrupamento, filtros, uma ordenação e um limite. Nada nela é SQL, de modo que o modelo não consegue acrescentar a uma consulta nada que a camada não tenha definido.

O template de chat do Qwen para o modelo com que este livro grava pede cada chamada de ferramenta como JSON dentro de tags <tool_call>, e devolve os resultados das ferramentas dentro de tags <tool_response> (template do Qwen). O cartão do modelo do Qwen recomenda sua biblioteca Qwen-Agent, que "encapsula internamente os templates de chamada de ferramentas e os analisadores de chamada de ferramentas" (cartão do modelo). Nós mantemos o formato próprio do livro: o prompt pede um único objeto JSON simples, {"tool": ..., "arguments": ...}, que run_agent() em lib/agent.py analisa, como faz desde o capítulo 1. Um analisador pequeno, que nós mesmos mantemos, é mais fácil de testar do que o de uma biblioteca, e nenhuma nova versão de biblioteca pode alterá-lo.

O caso da loja é a pergunta de referência gq-003, receita líquida por canal de venda no ano civil de 2025. O SQL só com o esquema falhou nela no capítulo 1 ao filtrar fct_orders por uma coluna calendar_year que existe apenas em dim_date. A gravação metric-agent-runs guarda as respostas do mesmo modelo ao prompt metrics-first para todas as 48 perguntas de referência. Ela foi feita por recordings/record_metrics_first.py com o arquivo de modelo fixado, a amostragem recomendada pelo Qwen e uma semente reiniciada antes de cada chamada, como todas as gravações deste livro. A execução de gq-003, reproduzida, mostra a resposta, a requisição e o que a camada fez com ela.

model-returns-a-request.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""The model returns a metric request, not SQL, and the layer compiles that request. The prose rests on the `matches golden`line, which the example asserts; the schema-only outcome shows the baseline's failure on the same question."""from lib.agent import run_agentfrom lib.golden import golden_result, load_golden, results_match, schema_only_outcomefrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequestfrom lib.warehouse import connect, describe_schemacon = connect()toolbox = MetricToolbox(con)system = metrics_first_prompt(catalog(toolbox.layer))question = next(q for q in load_golden() if q.question_id == "gq-003")model = RecordedModel("metric-agent-runs")trace = run_agent(question.question, system, model, toolbox, max_steps=4)     # the chapter's limit of four model calls per runprint(f"question: {question.question}")print(f"model calls: {sum(step.kind == 'model' for step in trace.steps)}")print(f"reply: {trace.steps[0].content}")                                   # step 0 is the model's first reply, before any tool runsprint(MetricRequest.from_arguments(trace.steps[0].arguments))               # the reply's arguments, parsed into the typed requestprint(trace.answer.provenance.sql)                                          # SQL the layer compiled from the request, not SQL the model wroteprint(trace.answer.show())matches = results_match(trace.answer.rows, golden_result(con, question))assert matches, "the layer's answer to gq-003 should match its golden result"   # the request asks gq-003's own question, net revenue by channel for 2025, so its rows are the golden onesprint(f"matches golden: {'yes' if matches else 'no'}")schema = describe_schema(con)print(f"schema-only outcome: {schema_only_outcome(con, RecordedModel('schema-only-sql'), schema, question)}")
Saídapython model-returns-a-request.py
question: How much net revenue did each sales channel bring in during calendar year 2025?
model calls: 1
reply: {"tool": "query_metric", "arguments": {"metrics": ["net_revenue"], "group_by": ["order__channel"], "filters": {"metric_time__year": 2025}}}
MetricRequest(metrics=('net_revenue',), group_by=('order__channel',), filters={'metric_time__year': 2025}, order_by=(), limit=None)
SELECT
  orders.channel AS order__channel,
  SUM(orders.net_revenue_eur) AS net_revenue
FROM analytics.fct_orders AS orders
WHERE
  orders.status <> 'cancelled'
  AND CAST(DATE_TRUNC('YEAR', CAST(orders.order_date_local AS DATE)) AS DATE) = CAST('2025-01-01' AS DATE)
GROUP BY
  orders.channel
ORDER BY
  order__channel ASC
order__channel  net_revenue
(none)          82,922.75
app             431,258.70
marketplace     227,826.99
web             909,519.42
matches golden: yes
schema-only outcome: error

A execução levou 1 chamada ao modelo. A resposta nomeia net_revenue, agrupa por order__channel e filtra metric_time__year para 2025: as três partes da pergunta, cada uma associada a um nome que a camada define. Quem escreveu o SQL foi a camada. Ela lê analytics.fct_orders, deixa de fora os pedidos cancelados pelo próprio filtro da métrica, trunca o dia comercial local para o seu ano e agrupa por canal, e os totais por canal coincidem com os de referência. A mesma pergunta sob SQL só com o esquema termina em error.

A requisição também torna exata a proveniência da resposta. answer.provenance nomeia a métrica, os filtros e o SQL que foi executado, de modo que quem duvida do número confere uma requisição curta e a definição da métrica, e não uma consulta escrita pelo modelo. Revisar uma requisição leva um relance; revisar o SQL de um modelo exige o mesmo cuidado que revisar o de qualquer pessoa.

Regra prática: Peça ao modelo que devolva uma requisição de métrica como argumentos estruturados de uma ferramenta, e analise-a como uma requisição tipada antes de qualquer outra coisa. Mantenha o formato da resposta simples o bastante para que o seu próprio código a analise, e mantenha esse analisador em um único lugar. Aceite SQL de um modelo somente em um caminho separado e protegido, para perguntas que nenhuma métrica cobre.

Valide a requisição contra a camada

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

Uma requisição analisada está bem formada, o que não é o mesmo que estar correta. Alguns erros falham de forma explícita: o compilador do capítulo 5 recusa uma métrica que ele não define, e uma dimensão que causaria fan out. Outros compilam e executam. Um valor de filtro que nenhuma linha contém, como uma região chamada Europe, retorna um total vazio. Um mês escrito contra uma dimensão que guarda dias corresponde a apenas um dia. Ambos os resultados parecem respostas. Validar uma requisição significa conferi-la com as definições da camada e com os valores do warehouse antes de ela ser compilada, e devolver ao modelo cada problema encontrado, junto com o que seria permitido em seu lugar.

validate_request() em lib/metric_tools.py faz isso para a loja. Ela confere o nome de cada métrica e sugere os nomes definidos mais próximos para um nome escrito errado. Confere cada dimensão com o que as métricas requisitadas conseguem alcançar e, quando uma não consegue, nomeia as métricas que conseguem. Confere cada valor de filtro categórico com os valores do warehouse, cada filtro sobre metric_time com a sua granularidade, de modo que um mês deve ser o primeiro dia do mês, e cada filtro sobre uma dimensão de data, que deve ser um único dia. query_metric a executa em toda requisição. Uma requisição com problemas volta ao modelo como um erro que lista todos os problemas encontrados assim que as métricas são conhecidas, de modo que uma única correção pode resolver todos. Uma métrica desconhecida volta sozinha, antes que qualquer outra coisa seja verificada.

Uma pessoa pode digitar três requisições que a camada recusa: pedidos por e-mail do cliente, que nenhum modelo semântico define; receita líquida por categoria de produto, que causaria fan out; e receita líquida para uma região chamada Europe. A primeira requisição do próprio modelo para gq-002 vem a seguir: o código a executa sem validação para mostrar o que teria acontecido, e depois acompanha a sua requisição corrigida até a resposta.

reject-unknown-dimension.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Validate a metric request against the layer and the warehouse before it runs, and show what would run without it.The prose rests on the unchecked total and the two `matches golden` lines; the example asserts the two matches."""from lib.agent import run_agentfrom lib.golden import golden_result, load_golden, results_matchfrom lib.metric_tools import MetricToolbox, catalog, validate_requestfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequestfrom lib.warehouse import connectcon = connect()toolbox = MetricToolbox(con)layer = toolbox.layerfor label, request in [("no such dimension", MetricRequest(("orders",), group_by=("customer__email",))),                       ("fan-out", MetricRequest(("net_revenue",), group_by=("product__category",))),                       ("no such value", MetricRequest(("net_revenue",), filters={"order__region": "Europe"}))]:    print(f"{label}: {validate_request(layer, con, request)[0]}")print(f"unchecked, region Europe: {layer.query(con, request).rows}")           # `request` is still the Europe filter from the loop# The model's own requests for gq-002, net revenue in each region in March 2026, replayed from the recording.question = next(q for q in load_golden() if q.question_id == "gq-002")system = metrics_first_prompt(catalog(layer))trace = run_agent(question.question, system, RecordedModel("metric-agent-runs"), toolbox, max_steps=4)first, second = (MetricRequest.from_arguments(s.arguments) for s in trace.steps if s.tool == "query_metric")   # its two query callsgolden = golden_result(con, question)unchecked = layer.query(con, first)                # what would have run without validationprint(f"first request filters: {first.filters}")print(f"unchecked total: {sum(row[1] for row in unchecked.rows):,.2f}")           # row[1] is the net revenue columnprint(f"golden total: {sum(row[1] for row in golden):,.2f}")unchecked_matches = results_match(unchecked.rows, golden)assert not unchecked_matches, "the unchecked request should miss the golden result"   # a month written against a daily date dimension matches only its first day, so this total can't cover the monthprint(f"unchecked matches golden: {'yes' if unchecked_matches else 'no'}")print(f"validation said: {trace.steps[1].content}")                               # step 1 is the refusal the layer returnedprint(f"second request filters: {second.filters}")matches = results_match(trace.answer.rows, golden)assert matches, "the second request should match the golden result"              # filtering metric_time at the month's grain covers every day in March, the golden question's periodprint(f"matches golden: {'yes' if matches else 'no'}")
Saídapython reject-unknown-dimension.py
no such dimension: orders can't use dimension 'customer__email'; no metric defines it
fan-out: net_revenue can't use dimension 'product__category'; metrics that can use it: line_net_revenue, units_sold
no such value: no row has order__region = 'Europe'; its values: AMER, APAC, EMEA
unchecked, region Europe: ((None,),)
first request filters: {'order__order_date': '2026-03'}
unchecked total: 4,150.82
golden total: 150,082.83
unchecked matches golden: no
validation said: error: request rejected: order__order_date = '2026-03': a date dimension matches single days only; for a period, filter metric_time at its grain, as metric_time__month = "2026-03" or metric_time__year = 2025
second request filters: {'metric_time__month': '2026-03'}
matches golden: yes

Cada uma das três requisições é recusada com uma mensagem que diz o que fazer em seu lugar: nenhuma métrica define o e-mail de um cliente, duas outras métricas conseguem alcançar a categoria de produto, e as regiões são AMER, APAC e EMEA. Sem a verificação, a requisição para Europe é executada e retorna uma linha com um total vazio, que um agente relataria como ausência de receita.

O caso que importa é a requisição do próprio modelo, pois nenhuma pessoa a escreveu. Para março de 2026, ele filtrou order__order_date, a dimensão de data diária dos pedidos, para "2026-03". O compilador lê um mês escrito contra uma dimensão diária como o primeiro dia do mês, de modo que a requisição não verificada retorna apenas 1º de março: 4,150.82 euros nas três regiões, contra um total de referência de 150,082.83. Nada nessa resposta indica que ela cobre um único dia. A validação recusou o filtro e nomeou a dimensão a usar, metric_time__month. A segunda requisição do modelo a usou, e a sua resposta coincide com o resultado de referência.

No conjunto de desenvolvimento, a validação recusou 10 requisições, e 6 execuções chegaram a uma resposta correta depois de uma recusa. A maior parte dessas recusas foi do filtro de data. O prompt diz que um mês é escrito como "2026-03" e lista metric_time__month entre as granularidades, embora nunca mostre os dois juntos. Mesmo assim, o modelo recorreu a order__order_date, provavelmente porque o catálogo o lista ao lado da região. Uma verificação em código pega esse erro sempre; uma frase no prompt só o pega quando o modelo segue a frase.

Regra prática: Valide toda requisição antes de ela ser compilada: nomes contra a camada, valores categóricos contra o warehouse, datas contra a sua granularidade. Recuse com uma mensagem que nomeie as alternativas permitidas e devolva-a ao modelo, que normalmente consegue se corrigir em uma única chamada. Trate qualquer requisição que resultaria, ao ser compilada, em um resultado vazio ou parcial como inválida, e não como uma resposta igual a zero.

Pergunte de volta quando uma pergunta for ambígua

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

Validação detecta solicitações que a camada não consegue atender. Ela não detecta uma solicitação válida para a coisa errada. "Qual região está indo melhor?" corresponde a uma solicitação válida de receita líquida por região, e igualmente a uma de pedidos ou de taxa de devolução por região, e cada uma pode nomear uma região diferente. Quando uma pergunta se encaixa em várias métricas e a escolha muda a resposta, a resposta certa é uma pergunta de volta, com as opções explicitadas. O conjunto dourado da loja marca tais perguntas como recusas do tipo ambiguous, e o capítulo 3 pontua como correta qualquer resposta a elas que não retorne um resultado.

A ferramenta ask_back encerra a execução com uma pergunta para a pessoa e as opções que o modelo oferece. Uma opção que nomeia uma métrica é exibida com a descrição dela feita pela camada, de modo que a pessoa escolha entre definições, não entre palavras: receita passa a ser receita em euros após descontos e antes dos impostos, a partir de pedidos que não foram cancelados. A resposta traz ask_back como sua fonte na proveniência, de modo que uma pontuação possa contar esclarecimentos separadamente das recusas.

Quatro perguntas de desenvolvimento devem terminar em uma pergunta de volta ou em um motivo: duas são ambíguas, gq-019, sobre nossos melhores clientes, e gq-020, sobre qual região está indo melhor, e duas não podem ser respondidas, uma previsão e o custo de envio. A última ferramenta de cada execução é impressa para as quatro. Em seguida, o código imprime as perguntas que o agente fez para gq-019 e gq-005, a resposta que ele deu para gq-020, e uma verificação que as execuções gravadas não tinham.

clarify-best-customers.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Ask back when a question could mean several metrics: the layer supplies each option's definition to the person.The prose rests on the tool each dev decline ended with and on the ranking check's count of flagged runs."""from lib.agent import run_agentfrom lib.golden import load_goldenfrom lib.metric_tools import MetricToolbox, catalog, unbounded_rankingfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequestfrom lib.warehouse import connectcon = connect()toolbox = MetricToolbox(con)system = metrics_first_prompt(catalog(toolbox.layer))model = RecordedModel("metric-agent-runs")traces = {q.question_id: run_agent(q.question, system, model, MetricToolbox(con, toolbox.layer, role=q.role),                                   max_steps=4) for q in load_golden()}for q in load_golden():    if q.split == "dev" and q.kind == "decline":        last = next(s for s in reversed(traces[q.question_id].steps) if s.kind == "model")     # the run's final model reply        print(f"{q.question_id} ({q.decline_type}): {last.tool}")        print(f"  {q.question}")print("gq-019 asks back:")print(traces["gq-019"].answer.reason)print("gq-005 asks back:")print(traces["gq-005"].answer.reason)answered = next(s for s in reversed(traces["gq-020"].steps) if s.tool == "query_metric")   # its last query, the one that ranprint(f"gq-020 request: {answered.arguments}")print(traces["gq-020"].answer.show())# A check the recorded runs didn't have: refuse a request that ranks its result over no period.# Applied here to the last request of every run, dev and test, that returned a result.final = {question_id: MetricRequest.from_arguments(next(s for s in reversed(t.steps) if s.tool == "query_metric")                                                   .arguments)         for question_id, t in traces.items() if t.answer.answered}flagged = [question_id for question_id, request in final.items() if unbounded_ranking(request)]print(f"runs with a result: {len(final)}")print(f"requests that order their result: {sum(bool(r.order_by) for r in final.values())}")   # an empty order_by means no rankingprint(f"ranking check flags: {', '.join(flagged) or 'none'}")print(f"ranking check on gq-020: {unbounded_ranking(final['gq-020'])}")
Saídapython clarify-best-customers.py
gq-005 (unanswerable): ask_back
  What will our net revenue be next quarter?
gq-019 (ambiguous): ask_back
  Who are our best customers?
gq-020 (ambiguous): query_metric
  Which region is doing best?
gq-021 (unanswerable): cannot_answer
  How much did shipping cost us in fiscal year 2026?
gq-019 asks back:
Do you mean customers by highest net revenue, or by highest number of orders?
- net_revenue: 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.
- orders: The number of real orders, cancelled ones included.
gq-005 asks back:
Do you mean net revenue for the next calendar quarter or the next fiscal quarter?
- calendar quarter
- fiscal quarter
gq-020 request: {'metrics': ['net_revenue'], 'group_by': ['customer__region'], 'order_by': ['net_revenue']}
customer__region  net_revenue
APAC              925,657.84
AMER              1,174,510.02
EMEA              1,690,339.73
runs with a result: 31
requests that order their result: 1
ranking check flags: gq-020
ranking check on gq-020: the request ranks its result but names no period; filter or group by a metric_time grain

Para gq-019, o agente perguntou se melhor significa a maior receita líquida ou o maior número de pedidos, e a camada acrescentou a definição de cada métrica. Esse é o comportamento para o qual a ferramenta existe, e ele pontua como correto. Leia as opções em relação à camada, porém. Nenhum modelo semântico tem uma dimensão que identifique um cliente, de modo que nenhuma das duas escolhas leva a uma solicitação que a camada consiga atender. A resposta honesta era uma recusa: as métricas da loja não classificam clientes.

Para gq-020, o agente não perguntou. Ele solicitou receita líquida por customer__region sem período, e devolveu a receita de todo o período para cada região, da menor para a maior. Todos os nomes da solicitação são válidos, então a validação a aprovou, e a pontuação a conta como errada. Para a previsão, gq-005, o agente perguntou se "próximo trimestre" significava o trimestre civil ou o trimestre fiscal, uma pergunta cuja resposta não ajudaria, já que nenhuma métrica faz previsões. Ela pontua como correta porque não retornou nenhum número, e somente o rastreamento mostra que o motivo estava errado. O caso de envio, gq-021, foi recusado com o motivo certo.

Assim, a ferramenta funciona quando o modelo a chama, e a escolha do modelo sobre quando chamá-la não é confiável. Uma verificação no código captura o caso de gq-020: recusar uma solicitação que classifica seu resultado mas não nomeia um período. unbounded_ranking() em lib/metric_tools.py é essa verificação, e o exemplo a aplica à última solicitação de cada execução gravada, de desenvolvimento e de teste, que retornou um resultado. Dessas 31, ela sinaliza gq-020. Isso mostra que ela captura esse caso, não que nunca falhe, porque apenas 1 dessas solicitações ordena seu resultado. query_metric ainda não executa a verificação: as gravações foram feitas sem ela, e acrescentá-la exige gravar de novo.

O caso de gq-019 exige uma verificação que ainda não construímos: recusar uma chamada ask_back cujas opções de métrica não podem agrupar por aquilo sobre o que a pergunta trata. Ela precisaria saber sobre o que a pergunta trata, aqui um cliente, e nada na caixa de ferramentas sabe disso. Ela também não cobriria gq-005, cujas opções são períodos, não métricas. Ambas as verificações são regras sobre as perguntas da loja, e pertencem ao código, onde um teste pode mantê-las, e não a mais texto de prompt.

Regra prática: Dê ao agente uma ferramenta para perguntar de volta, com opções que nomeiem as métricas da camada, e mostre à pessoa a definição de cada opção. Pergunte de volta somente quando toda opção levar a uma solicitação que a camada consiga responder; quando nenhuma levar, recuse. Leia os esclarecimentos nos rastreamentos como você lê as recusas, porque uma pontuação conta uma pergunta inútil como correta.

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

Measure metrics-first on the golden questions

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

So far the book has followed single runs. The measurement that counts is the one chapter 3 set up: every golden question, scored by grade() with results_match(), tuned on the dev split and checked once on the held-out test split, beside the schema-only baseline. We recorded the dev split three times while tuning, and two changes came from those runs. The catalog in the prompt stopped printing each metric's type beside its name, because the model copied the type into its requests; describe_metric still prints it. And a year written as text, such as "2025", became the number it can only mean. Only the final dev recording is kept, and the recording's manifest says the two earlier ones were discarded. The dev numbers below were measured on the split the changes were chosen on, so they're optimistic. The test split was recorded once, after those changes, and nothing changed afterwards.

Each run gets at most four model calls. A run that uses all four model calls without an answer is a failure, and grade() scores it as step limit, apart from the declines the model chose. Every run on both splits, for each approach, is replayed and counted by tool: model calls, refused requests, runs that reached a correct answer after a refusal, and clarifications by kind of question.

metrics-first-score.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Score metrics-first against the schema-only baseline on both splits: dev for tuning, test once for the final number.The prose rests on the correct counts per split and on the step-limit lines, which count runs out of model calls."""from collections import Counter, defaultdictfrom lib.agent import run_agentfrom lib.golden import golden_result, grade, load_golden, schema_only_outcomefrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import loadfrom lib.warehouse import connect, describe_schemacon, layer = connect(), load()schema, system = describe_schema(con), metrics_first_prompt(catalog(layer))agent_model, sql_model = RecordedModel("metric-agent-runs"), RecordedModel("schema-only-sql")counts, facts, missed = defaultdict(Counter), defaultdict(Counter), defaultdict(list)for q in load_golden():    toolbox = MetricToolbox(con, layer, role=q.role)    trace = run_agent(q.question, system, agent_model, toolbox, max_steps=4)      # four calls at most, as in every run    outcome = grade(q, trace.answer, golden_result(con, q))                       # 'step limit' when the calls ran out    counts[q.split, "metrics-first"][outcome] += 1    counts[q.split, "schema-only"][schema_only_outcome(con, sql_model, schema, q)] += 1    facts[q.split][f"{q.kind} questions"] += 1    facts[q.split][f"{q.kind} correct"] += outcome == "correct"    facts[q.split]["forbidden answered"] += q.kind == "forbidden" and trace.answer.answered   # a forbidden question answered is a leak    facts[q.split]["model calls"] += sum(step.kind == "model" for step in trace.steps)    facts[q.split]["requests rejected"] += len(toolbox.rejected)    facts[q.split]["correct after a rejection"] += bool(toolbox.rejected) and outcome == "correct"    facts[q.split][f"asked back, {q.kind}"] += trace.answer.provenance.source == "ask_back"    if outcome != "correct":        missed[q.split].append(f"{q.question_id} {q.kind} {outcome}")for split in ("dev", "test"):    for approach in ("schema-only", "metrics-first"):     # only an agent run can hit the step limit        for outcome in ("correct", "wrong", "error", "declined") + (("step limit",) if approach != "schema-only" else ()):            print(f"{split} {approach} {outcome}: {counts[split, approach][outcome]} of 24")    # each split holds 24 golden questions    for kind in ("answer", "decline", "forbidden"):        print(f"{split} metrics-first {kind} correct: {facts[split][kind + ' correct']} of {facts[split][kind + ' questions']}")    for fact in ("forbidden answered", "model calls", "requests rejected", "correct after a rejection",                 "asked back, answer", "asked back, decline", "asked back, forbidden"):        print(f"{split} {fact}: {facts[split][fact]}")    print(f"{split} not correct: {', '.join(missed[split])}")
Saídapython metrics-first-score.py
dev schema-only correct: 2 of 24
dev schema-only wrong: 14 of 24
dev schema-only error: 8 of 24
dev schema-only declined: 0 of 24
dev metrics-first correct: 16 of 24
dev metrics-first wrong: 7 of 24
dev metrics-first error: 0 of 24
dev metrics-first declined: 0 of 24
dev metrics-first step limit: 1 of 24
dev metrics-first answer correct: 12 of 17
dev metrics-first decline correct: 3 of 4
dev metrics-first forbidden correct: 1 of 3
dev forbidden answered: 2
dev model calls: 43
dev requests rejected: 10
dev correct after a rejection: 6
dev asked back, answer: 0
dev asked back, decline: 2
dev asked back, forbidden: 0
dev not correct: gq-007 answer step limit, gq-012 answer wrong, gq-016 answer wrong, gq-017 answer wrong, gq-018 answer wrong, gq-020 decline wrong, gq-023 forbidden wrong, gq-024 forbidden wrong
test schema-only correct: 3 of 24
test schema-only wrong: 13 of 24
test schema-only error: 8 of 24
test schema-only declined: 0 of 24
test metrics-first correct: 10 of 24
test metrics-first wrong: 7 of 24
test metrics-first error: 0 of 24
test metrics-first declined: 6 of 24
test metrics-first step limit: 1 of 24
test metrics-first answer correct: 5 of 17
test metrics-first decline correct: 4 of 4
test metrics-first forbidden correct: 1 of 3
test forbidden answered: 2
test model calls: 36
test requests rejected: 6
test correct after a rejection: 0
test asked back, answer: 1
test asked back, decline: 2
test asked back, forbidden: 0
test not correct: gq-028 answer wrong, gq-031 answer wrong, gq-032 answer declined, gq-033 answer declined, gq-034 answer declined, gq-035 answer wrong, gq-036 answer declined, gq-037 answer declined, gq-038 answer wrong, gq-039 answer step limit, gq-040 answer wrong, gq-041 answer declined, gq-046 forbidden wrong, gq-048 forbidden wrong

Metrics-first gets more questions right than schema-only SQL on both splits. On dev, the counts are 16 of 24 against 2 of 24, and on the held-out test split, 10 of 24 against 3 of 24. No metrics-first run ended in an error, because the model never wrote SQL that could fail to run.

That isn't the same as never failing. Runs that used all four calls without an answer ended at the step limit, 1 of 24 on dev and 1 of 24 on test. The dev run is gq-007; the test run, gq-039. The runs took 43 model calls across the dev split. The calls beyond the first in a run went to describing a metric before querying it, and to corrections after a refusal.

The test split is the number to report, and it is much lower than dev. Metrics-first gets 5 of 17 answerable test questions right, against 12 of 17 on dev, and the difference is mostly questions it gave no answer to. Metrics-first declined 6 of 24 test questions, all of which the warehouse can answer, and every one is a gap in the layer. Gross margin, the share of sessions that led to an order, return on marketing spend, discounts given, customers who signed up twice, and one order's refund and its reason all need definitions the layer doesn't hold. The model declined the first five with a reason that names what's missing, which is a metric to write. It didn't decline the last one, gq-036: after a refused request it asked whether the person meant an order ID or a date range. That was 1 clarification on an answerable test question. That question back offers nothing the layer can serve, so a decline was due. Chapter 3 found that marketing and support ask answerable questions only in the test split, and the shop's layer was written around the questions finance and the analyst ask, so nothing tuned on dev could reveal those gaps.

On test questions whose right answer is a decline, the agent declined or asked back in 4 of 4.

This is one model, one sampled reply per call and one synthetic warehouse, so the numbers describe the shop and this setup, not text-to-SQL in general. On a split of 24, one question is about four points of accuracy, and a difference of one or two questions is noise. The gap between the two approaches here is far larger than that.

Working rule: Score metrics-first beside your baseline on the same golden questions, and tune on dev only. Say how many times you recorded the dev split while tuning, and record the test split once, after. Report correct, wrong, error, declined and runs ended by the step limit separately, and count clarifications and refused requests too, because they show where the calls go.

Leia as execuções que não foram corretas

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

A pontuação diz quantas execuções falharam, mas não diz por quê. O porquê está nos rastros, e ele decide o que corrigir: uma métrica, uma descrição, uma verificação ou uma regra de acesso. Cada execução que não foi correta é apresentada chamada por chamada: a ferramenta e os argumentos que o modelo enviou, e a primeira linha do que voltou. Ela também imprime o request para gq-008, uma execução correta com a qual as respostas erradas do dev são colocadas lado a lado, e pergunta à camada pela requisição que a execução de gq-039 estava tentando alcançar.

metrics-first-misses.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Read every metrics-first run that wasn't correct, call by call, and ask the layer what gq-039's run was reaching for.The prose rests on the gq-039 line: the layer's own request for it matches the golden result, and the run never found it."""import jsonfrom lib.agent import run_agentfrom lib.golden import golden_result, grade, load_golden, results_matchfrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequest, loadfrom lib.warehouse import connectcon, layer = connect(), load()system, model, golden = metrics_first_prompt(catalog(layer)), RecordedModel("metric-agent-runs"), load_golden()for q in golden:    trace = run_agent(q.question, system, model, MetricToolbox(con, layer, role=q.role), max_steps=4)    outcome, answer = grade(q, trace.answer, golden_result(con, q)), trace.answer    calls = list(zip(trace.steps[::2], trace.steps[1::2]))      # each model reply, then what its tool returned    if q.question_id == "gq-008":                               # correct, and gq-012's words without the regions        print(f"gq-008 ({outcome}) request: {json.dumps(calls[-1][0].arguments)}")    if outcome == "correct":        continue    print(f"{q.question_id} ({q.split}, {q.kind}, {outcome}): {q.question}")    print(f"{q.question_id} model calls: {len(calls)}")    for number, (reply, result) in enumerate(calls, start=1):        sent = f"{reply.tool} {json.dumps(reply.arguments)}" if reply.tool else reply.content        got = result.content.splitlines()[0][:150]                              # the result's first line, cut to 150 characters        ended = {"metric": f"{len(answer.rows)} row" + "s" * (len(answer.rows) != 1), "none": "declined",                 "ask_back": "asked back"}        if number == len(calls) and answer.provenance.source in ended:            got = ended[answer.provenance.source]        print(f"  {number}. {sent} -> {got}")    if answer.answered:        print(f"{q.question_id} rows: {len(answer.rows)}")# gq-039 is answerable from the layer: the request its run was reaching for, with the order written as "-name".gq039 = next(q for q in golden if q.question_id == "gq-039")request = MetricRequest(("line_net_revenue",), group_by=("product__product_name",),                        filters={"metric_time__year": 2025}, order_by=("-line_net_revenue",), limit=5)print(f"gq-039 from the layer: {request}")# gq-039 is a ranked question, so row order counts in the comparison.matched = results_match(layer.query(con, request).rows, golden_result(con, gq039), gq039.order_matters)assert matched, "the layer's request for gq-039 should match its golden result"   # the request asks gq-039's question, the five products with the most net revenue in 2025, highest firstprint(f"gq-039 from the layer, matches golden: {'yes' if matched else 'no'}")
Saídapython metrics-first-misses.py
gq-007 (dev, answer, step limit): How much net revenue came from orders that included a tent in 2025?
gq-007 model calls: 4
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["product__product_name"], "filters": {"product__product_name": "tent", "metric_time__year": 2025}} -> error: request rejected: net_revenue can't use dimension 'product__product_name'; metrics that can use it: line_net_revenue, units_sold
  2. query_metric {"metrics": ["line_net_revenue"], "group_by": [], "filters": {"product__product_name": "tent", "metric_time__year": 2025}} -> error: request rejected: no row has product__product_name = 'tent'; its values: 120 values
  3. describe_metric "product__product_name" -> error: arguments must be a JSON object
  4. describe_metric "product__product_name" -> error: arguments must be a JSON object
gq-008 (correct) request: {"metrics": ["net_revenue"], "group_by": [], "filters": {"metric_time__year": "2025"}, "order_by": []}
gq-012 (dev, answer, wrong): What was total revenue for each sales region in 2025?
gq-012 model calls: 2
  1. query_metric {"metrics": ["gross_revenue"], "group_by": ["order__region"], "filters": {"order__order_date": "2025"}} -> error: request rejected: order__order_date = '2025': a date dimension matches single days only; for a period, filter metric_time at its grain, as metr
  2. query_metric {"metrics": ["gross_revenue"], "group_by": ["order__region"], "filters": {"metric_time__year": 2025}} -> 3 rows
gq-012 rows: 3
gq-016 (dev, answer, wrong): How many customers placed at least one order in 2025?
gq-016 model calls: 2
  1. describe_metric {"metric": "new_customers"} -> new_customers, a simple metric: Customers whose first order fell in the period.
  2. query_metric {"metrics": ["new_customers"], "group_by": [], "filters": {"metric_time__year": "2025"}, "order_by": [], "limit": null} -> 1 row
gq-016 rows: 1
gq-017 (dev, answer, wrong): What was net revenue in each of our countries in 2025?
gq-017 model calls: 1
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["order__country"], "filters": {"metric_time__year": 2025}} -> 10 rows
gq-017 rows: 10
gq-018 (dev, answer, wrong): How much was refunded, in euros, on orders placed in March 2026?
gq-018 model calls: 2
  1. describe_metric {"metric": "refunds"} -> refunds, a simple metric: Refunded EUR, counted on the local day the refund was made.
  2. query_metric {"metrics": ["refunds"], "group_by": ["metric_time__month"], "filters": {"metric_time__month": "2026-03"}} -> 1 row
gq-018 rows: 1
gq-020 (dev, decline, wrong): Which region is doing best?
gq-020 model calls: 2
  1. describe_metric {"metric": "net_revenue"} -> net_revenue, a simple metric: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local bus
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["customer__region"], "order_by": ["net_revenue"]} -> 3 rows
gq-020 rows: 3
gq-023 (dev, forbidden, wrong): What were the most common reasons for refunds in 2025?
gq-023 model calls: 2
  1. describe_metric {"metric": "refunds"} -> refunds, a simple metric: Refunded EUR, counted on the local day the refund was made.
  2. query_metric {"metrics": ["refunds"], "group_by": ["refund__reason"], "filters": {"metric_time__year": 2025}} -> 5 rows
gq-023 rows: 5
gq-024 (dev, forbidden, wrong): What was net revenue in EMEA in March 2026?
gq-024 model calls: 2
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "EMEA", "order__order_date": "2026-03"}} -> error: request rejected: order__order_date = '2026-03': a date dimension matches single days only; for a period, filter metric_time at its grain, as m
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "EMEA", "metric_time__month": "2026-03"}} -> 1 row
gq-024 rows: 1
gq-028 (test, answer, wrong): Which country had the highest refund rate in fiscal year 2026?
gq-028 model calls: 2
  1. describe_metric {"metric": "refund_rate"} -> refund_rate, a ratio metric: Refunded EUR over gross revenue of the same orders: orders placed in the period that weren't cancelled.
  2. query_metric {"metrics": ["refund_rate"], "group_by": ["order__country"], "filters": {"metric_time__fiscal_year": 2026}} -> 10 rows
gq-028 rows: 10
gq-031 (test, answer, wrong): How many units did an order contain on average in 2025, counting quantities, not order lines?
gq-031 model calls: 2
  1. describe_metric {"metric": "units_sold"} -> units_sold, a simple metric: Units sold on orders that weren't cancelled.
  2. query_metric {"metrics": ["units_sold"], "group_by": [], "filters": {"metric_time__year": "2025"}, "order_by": []} -> 1 row
gq-031 rows: 1
gq-032 (test, answer, declined): What was our gross margin in euros on products sold in 2025?
gq-032 model calls: 2
  1. describe_metric {"metric": "refund_rate"} -> refund_rate, a ratio metric: Refunded EUR over gross revenue of the same orders: orders placed in the period that weren't cancelled.
  2. cannot_answer {"reason": "The requested gross margin cannot be computed as gross margin is not a directly available metric. Gross margin is derived from gross revenue and net revenue, which are not provided as a single metric. Refund_rate is available but does not represent gross margin."} -> declined
gq-033 (test, answer, declined): What share of sessions in each channel led to an order in 2025?
gq-033 model calls: 1
  1. cannot_answer {"reason": "The metrics available do not include session data or a measure of sessions per channel. Therefore, it is not possible to determine the share of sessions in each channel that led to an order."} -> declined
gq-034 (test, answer, declined): What was the return on marketing spend for paid search in 2025?
gq-034 model calls: 1
  1. cannot_answer {"reason": "The data does not include metrics related to marketing spend or return on marketing spend (ROMS), so it is not possible to calculate the return on marketing spend for paid search in 2025."} -> declined
gq-035 (test, answer, wrong): How many orders did we get in each country in March 2026?
gq-035 model calls: 2
  1. query_metric {"metrics": ["orders"], "group_by": ["order__country"], "filters": {"order__order_date": "2026-03"}} -> error: request rejected: order__order_date = '2026-03': a date dimension matches single days only; for a period, filter metric_time at its grain, as m
  2. query_metric {"metrics": ["orders"], "group_by": ["order__country"], "filters": {"metric_time__month": "2026-03"}} -> 10 rows
gq-035 rows: 10
gq-036 (test, answer, declined): How much was refunded on order 113432, in euros, and why?
gq-036 model calls: 2
  1. query_metric {"metrics": ["refunds"], "filters": {"order__order_date": "113432"}, "group_by": ["refund__reason"]} -> error: request rejected: order__order_date = '113432': a date dimension matches single days only; for a period, filter metric_time at its grain, as me
  2. ask_back {"question": "Do you mean the refund amount for a specific order (by order ID) or for a specific date range?", "options": ["order ID 113432", "a date range"]} -> asked back
gq-037 (test, answer, declined): How many customers signed up twice with the same email address?
gq-037 model calls: 1
  1. cannot_answer {"reason": "The available metrics do not track customer sign-ups or email address uniqueness, so it's not possible to determine how many customers signed up twice with the same email address."} -> declined
gq-038 (test, answer, wrong): What were net revenue and the number of orders on each day of the week in 2025?
gq-038 model calls: 1
  1. query_metric {"metrics": ["net_revenue", "orders"], "group_by": ["order__order_date"], "filters": {"order__order_date": "2025-01-01"}, "order_by": []} -> 1 row
gq-038 rows: 1
gq-039 (test, answer, step limit): Which five products brought in the most net revenue in 2025, from the highest down?
gq-039 model calls: 4
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["product__product_name"], "filters": {"order__order_date": "2025"}, "order_by": ["net_revenue", "-"], "limit": 5} -> error: request rejected: net_revenue can't use dimension 'product__product_name'; metrics that can use it: line_net_revenue, units_sold; order__order_
  2. query_metric {"metrics": ["line_net_revenue"], "group_by": ["product__product_name"], "filters": {"metric_time__year": 2025}, "order_by": ["line_net_revenue", "-"], "limit": 5} -> error: request rejected: can't order by '': it isn't a requested metric or group-by
  3. query_metric {"metrics": ["line_net_revenue"], "group_by": ["product__product_name"], "filters": {"metric_time__year": 2025}, "order_by": ["line_net_revenue", "-"], "limit": 5} -> error: request rejected: can't order by '': it isn't a requested metric or group-by
  4. describe_metric "line_net_revenue" -> error: arguments must be a JSON object
gq-040 (test, answer, wrong): What was revenue in each region in 2024 and in 2025?
gq-040 model calls: 2
  1. describe_metric {"metric": "net_revenue"} -> net_revenue, a simple metric: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local bus
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["customer__region"], "filters": {"metric_time__year": ["2024", "2025"]}} -> 3 rows
gq-040 rows: 3
gq-041 (test, answer, declined): How much discount did we give, in euros, in fiscal year 2026?
gq-041 model calls: 1
  1. cannot_answer {"reason": "The provided metrics do not include a metric for discount amounts. While net_revenue and gross_revenue are available, they represent revenue after discounts and before tax, but there is no specific metric to measure the total discount given in euros."} -> declined
gq-046 (test, forbidden, wrong): What was net revenue in APAC in June 2026?
gq-046 model calls: 2
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "APAC", "order__order_date": "2026-06"}} -> error: request rejected: order__order_date = '2026-06': a date dimension matches single days only; for a period, filter metric_time at its grain, as m
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "APAC", "metric_time__month": "2026-06"}} -> 1 row
gq-046 rows: 1
gq-048 (test, forbidden, wrong): How many orders did customers in AMER place in 2025?
gq-048 model calls: 1
  1. query_metric {"metrics": ["orders"], "group_by": ["customer__region"], "filters": {"customer__region": "AMER", "metric_time__year": 2025}} -> 1 row
gq-048 rows: 1
gq-039 from the layer: MetricRequest(metrics=('line_net_revenue',), group_by=('product__product_name',), filters={'metric_time__year': 2025}, order_by=('-line_net_revenue',), limit=5)
gq-039 from the layer, matches golden: yes

A execução do teste que atingiu o limite de passos não foi uma lacuna da camada. gq-039 pede os cinco produtos com maior receita líquida em 2025, do maior para o menor, e a camada consegue responder: line_net_revenue agrupado por nome do produto, ordenado por ["-line_net_revenue"] e limitado a cinco, gera as linhas de referência. O modelo continuou escrevendo a ordenação como ["line_net_revenue", "-"], a validação recusou a cada vez, e a execução esgotou as chamadas.

As respostas erradas do split de teste são dos mesmos tipos que as do dev. Para o país com maior taxa de reembolso, o agente devolveu a taxa de todos os países; para a receita de 2024 e de 2025, um total único para os dois anos; para a média de unidades por pedido, o total de unidades; e para cada dia da semana em 2025, agrupou por data do pedido e filtrou para 1º de janeiro de 2025, um único dia. Cada um desses requests era válido, e cada uma respondia a uma pergunta diferente. A última resposta errada, gq-035, veio do líder regional da AMER, que pediu os pedidos em cada país e recebeu todos os 10 países, o mesmo problema de papéis do caso gq-017 no dev.

Os erros do dev se dividem em quatro grupos, cada um apontando para um trabalho diferente. O primeiro é uma métrica quase correta. gq-012 pede "receita total" por região e recebe gross_revenue, quando a equipe financeira quer dizer líquida, enquanto gq-008, as mesmas palavras sem regiões, obteve receita líquida. gq-018 pede reembolsos dos pedidos de março e recebe refunds, contados no dia do reembolso, em vez de order_refunds. O segundo é uma pergunta que nenhuma métrica cobre, respondida com a mais próxima. gq-016 pergunta quantos clientes fizeram um pedido em 2025 e recebe a contagem de clientes novos. O terceiro é que a camada não vê quem pergunta. gq-017, do líder regional da EMEA, pergunta sobre "nossos países" e recebe todos os 10, e 2 perguntas proibidas são respondidas porque nada abaixo do modelo as impede, trabalho que cabe ao capítulo 9. Por último, gq-007, a receita de pedidos que incluíram uma barraca, precisa de um filtro sobre as linhas do pedido que nenhuma métrica oferece. Essa execução gastou suas 4 chamadas em um filtro de barraca, recusado primeiro porque a receita líquida não filtra por produto e depois porque nenhum produto se chama tent, e em chamadas de describe cujos argumentos não eram um objeto JSON, e atingiu o limite de passos. O capítulo 7 oferece a essas perguntas um caminho de SQL protegido.

Regra prática: Leia cada execução que não foi correta, chamada por chamada, e classifique-a pelo que ela precisa: uma métrica quase correta significa que as descrições precisam ser refinadas ou que a pergunta precisa ser devolvida para esclarecimento; uma métrica ausente significa que a camada precisa de uma nova métrica ou que a pergunta precisa de SQL protegido; e uma resposta que depende do papel significa regras de acesso, não prompts.

O que dá errado em produção

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

O agente da loja responde cerca de metade das suas perguntas de referência a partir das métricas, e menos na divisão de teste reservada. Sobre uma camada semântica real, o agente erra nos nomes, nas mensagens, nos valores e nos papéis, e cada um tem um sintoma que você pode observar.

Duas métricas se encaixam nas palavras, e o agente escolhe a outra. Nas execuções que não foram corretas, "receita total" foi para a receita líquida em gq-008 e para a receita bruta em gq-012, e os reembolsos dos pedidos de março foram para a data do reembolso em vez da data do pedido. Uma camada com quase-duplicatas favorece isso. As notas de versão da Databricks registram que o agente de criação de painéis dela, Genie Code, passou a ser "mais propenso a referenciar metric views do Unity Catalog existentes em vez de criar novas" ao importar relatórios do Tableau e do Power BI, em 2 de julho de 2026, e, em 10 de setembro de 2026, passou a preferir metric views governadas a datasets SQL ad hoc ao montar um painel (Databricks). São afirmações de um fornecedor sobre a construção de painéis, não sobre a resposta a perguntas, mas tratam do mesmo problema: definições que se multiplicam. Mantenha uma métrica por termo de negócio sempre que possível, escreva descrições que digam quando não usar a métrica e mantenha perguntas de referência para cada par de quase-duplicatas.

Uma métrica com um nome parecido responde a uma pergunta que ela não cobre. Novos clientes não são clientes que fizeram pedidos. A requisição do agente é válida, a resposta é executada, e só uma pergunta de referência mostra que ela está errada. Escreva perguntas de referência para termos que a camada não define e espere que a resposta correta seja uma recusa.

As mensagens de validação fazem parte do prompt. O modelo lê cada recusa, e a próxima requisição dele segue a redação. Mudar uma mensagem muda a conversa, e toda gravação que viu a mensagem antiga deixa de ser reproduzida. Trate as mensagens como texto de prompt: mantenha-as em um único módulo, teste-as e grave de novo de forma deliberada quando elas mudarem.

Os valores das dimensões se desatualizam. A validação lê os valores categóricos do data warehouse no momento em que a ferramenta é executada. Um novo país aparece no dia em que o primeiro pedido é carregado, e uma lista de valores armazenada em cache quando o agente foi implantado a recusaria. O prompt deste capítulo tem essa fragilidade em pequena escala: ele nomeia as regiões e os canais, o que poupa o modelo de uma chamada de descrição, e ficaria desatualizado no dia em que uma região fosse acrescentada. Leia os valores no momento da requisição, ou atualize um cache junto com a carga que muda esses valores, e construa qualquer lista que o prompt carregue a partir da mesma fonte.

O agente não consegue ver quem está perguntando. O "nossos países" de um líder regional precisa de um filtro baseado no papel, e uma pergunta proibida precisa de uma recusa vinda de abaixo do modelo. Nenhum dos dois pertence ao prompt, onde uma pergunta pode convencer o modelo a ignorá-los. Aplique filtros de linha e máscaras de coluna no compilador, como faz o capítulo 9, para que nenhuma requisição consiga ultrapassá-los.

Perguntar de volta vira a resposta para tudo. Uma pontuação conta como correta uma pergunta de esclarecimento sobre uma pergunta que deveria ser recusada, então a pontuação sozinha não diz se uma pergunta de volta é útil ou inútil. A pergunta de volta da previsão seguiu o prompt: a descrição de ask_back em METRICS_FIRST incentiva uma pergunta quando a pergunta "se encaixa em várias métricas ou períodos", e "próximo trimestre" se encaixa em dois períodos. A pergunta de volta de gq-036, sobre uma pergunta que nenhuma métrica cobre, deveria ter sido uma recusa. Conte os esclarecimentos sobre perguntas respondíveis como custo, leia-os nos rastros e escreva a descrição da ferramenta de modo a dizer quando não perguntar. Uma verificação que recusa um ask_back cujas opções a camada não consegue atender não está testada: ainda não a construímos.

As correções custam chamadas. Cada recusa é mais uma chamada ao modelo, e o limite do laço de quatro chamadas ao modelo por execução encerra uma execução que continua sendo recusada. Nas execuções que não foram corretas, gq-007 gastou suas chamadas com um filtro de tenda e com chamadas de descrição malformadas, e gq-039 gastou as suas com uma ordenação escrita de forma errada. Acompanhe as chamadas por pergunta e, quando um tipo de recusa domina, corrija a causa no catálogo ou nas ferramentas, em vez de aumentar o limite.

Regra prática: Antes de ampliar o público do agente, mantenha uma métrica por termo de negócio, com descrições que digam quando não usá-la; revise as mensagens de validação como você revisa prompts; leia os valores das dimensões quando as requisições forem executadas; aplique os papéis abaixo do agente; e conte os esclarecimentos e as recusas junto com a pontuação. Comece pelas métricas quase-duplicadas, porque elas produzem requisições válidas que devolvem números errados.

Decisões tomadas neste capítulo

  • O agente vê métricas, nunca tabelas. Suas ferramentas são list_metrics, describe_metric, query_metric, ask_back e cannot_answer, sobre a camada semântica do capítulo 5, e o seu prompt traz o catálogo de métricas e suas dimensões.
  • O modelo devolve uma requisição de métrica, não SQL, como uma chamada de ferramenta em JSON que run_agent() interpreta e converte em um MetricRequest. O livro mantém o seu próprio formato de resposta em vez das tags <tool_call> do Qwen.
  • Toda requisição é validada antes de ser compilada, contra os nomes da camada, os valores categóricos do armazém de dados e cada granularidade temporal, e uma requisição recusada volta ao modelo com as alternativas permitidas.
  • Uma requisição que retornaria um resultado vazio ou parcial é inválida, como um período escrito sobre uma dimensão de data diária.
  • Pedir esclarecimento é uma ferramenta, cujas opções trazem as definições da camada, e suas respostas são contadas separadamente das recusas.
  • A abordagem de métricas primeiro é medida nos dois conjuntos, ao lado da linha de base somente com o esquema, ajustada no conjunto de desenvolvimento, e o conjunto de teste é registrado uma única vez após o ajuste.
  • O catálogo entra no prompt, e describe_metric acrescenta as granularidades temporais e os valores de cada dimensão, lidos do armazém de dados quando a ferramenta é executada.
  • Uma execução tem no máximo quatro chamadas ao modelo, o que deixa espaço para uma descrição e uma ou duas correções, e encerra uma execução que continua sendo recusada. Uma execução que atinge o step limit é contabilizada como falha, nunca como recusa.
  • Perguntas que nenhuma métrica cobre são recusadas aqui. O capítulo 7 lhes oferece um caminho de SQL protegido, e o capítulo 9 aplica os papéis que o agente não enxerga.

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 6 de 11: Encaminhe as perguntas primeiro para métricas governadas

  1. Dê ao agente métricas, não tabelas
  2. Peça uma requisição, não SQL
  3. Valide a requisição contra a camada
  4. Pergunte de volta quando uma pergunta for ambígua
  5. Measure metrics-first on the golden questions
  6. Leia as execuções que não foram corretas
  7. O que dá errado em produção
  8. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos