Registre cada execução e conte o que ela custou
Cerca de 23 minutos min de leitura, com 4 exemplos em 8 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.2. Leia o original
Ao final deste capítulo, você será capaz de fazer com que cada execução grave um registro por passo em um arquivo que um leitor posterior possa analisar, dar a cada registro IDs que o liguem à sua execução e à sua chamada, e dizer quanto a execução custou em tokens. Custo, aqui, significa contagens. Nunca significa dinheiro.
O agente de manutenção faz as suas execuções em unitcraft em uma cópia descartável. Uma execução pode terminar bem, mal ou não terminar, e o motivo de parada diz apenas como ela terminou. Tome a execução do capítulo 1 sobre T-01, uma das tarefas do conjunto de tarefas. Ela lê o arquivo certo e roda os testes, depois faz uma sequência de chamadas malformadas até atingir o limite de passos. O motivo de parada é step_cap, e isso é tudo o que o motivo de parada diz. Ele não diz o que as chamadas malformadas tinham em comum, o que o harness fez com cada uma delas, nem quantos tokens cada passo usou. Essas respostas estão nos passos, e por isso o harness precisa manter os passos.
O registro de cada passo é o trace. A pontuação do capítulo 10 já lê as contagens armazenadas, e um leitor que pergunta por que uma execução parou precisa dos passos que vêm antes da parada. Este capítulo grava o trace como dados, dá aos seus IDs uma forma fixa e conta o que ele contém. Toda contagem aqui é lida de uma gravação ou impressa por um script. Nenhuma foi tirada de um modelo em execução; por isso, as contagens são contagens armazenadas, e a única verificação que as recalcularia a partir do modelo não foi executada.
Uma linha por evento
Um trace é um arquivo com um objeto JSON por linha. O formato tem um nome, JSON Lines, e uma definição curta: cada linha contém um valor JSON, o arquivo está em UTF-8, e um line feed encerra cada linha. A página recomenda um line feed também após a última linha, mas não o exige, e aceita também um carriage return seguido de line feed. O formato JSON Lines diz que não se deve incluir uma byte order mark. O harness grava cada registro com as chaves ordenadas, sem espaços e somente em ASCII, de modo que o mesmo registro sempre sai como os mesmos bytes. Isso importa pelo mesmo motivo que importa a saída impressa: o leitor pode comparar dois traces linha a linha.
Reproduzir a execução do capítulo 1 sobre T-01 grava seus passos nesta forma. A reprodução lê a resposta gravada para cada passo, de modo que o trace é o mesmo em toda execução.
1"""The chapter 1 recorded run of T-01 as JSON lines: one record per step, with run-scoped IDs and the recorded token2counts. The lines are written to a file and read back, and the reader counts the empty pieces it skips."""3import json4import tempfile5from pathlib import Path67from lib.case import load_tasks8from lib.loop import run_task9from lib.models import ReplayModel10from lib.tools import CH111from lib.trace import IdCounter, StepRecorder, dumps, read_lines, step_records1213task = load_tasks(only=["T-01"])[0]14model = StepRecorder(ReplayModel("chapter-1-t01", "T-01"))15run = run_task(model, task, CH1, max_steps=CH1.step_cap, ids=IdCounter())16records = step_records(run, model)17for record in records:18 print(dumps(record))19print("records:", len(records))20print("first call ID:", records[0]["calls"][0])21print("results:", ", ".join(f"step {r['step']} {r['result']}" for r in records))22print("prompt tokens, summed over the records:", sum(r["prompt_tokens"] for r in records))23print("completion tokens, summed over the records:", sum(r["completion_tokens"] for r in records))24try:25 json.loads("") # a blank line is not a JSON value26except json.JSONDecodeError as error:27 print("blank line:", error)28with tempfile.TemporaryDirectory() as folder:29 path = Path(folder) / "trace.jsonl"30 path.write_text("".join(dumps(record) + "\n" for record in records), encoding="utf-8")31 read_back, skipped = read_lines(path.read_text(encoding="utf-8"))32print("lines read back:", len(read_back))33print("empty pieces skipped:", skipped)34assert read_back == records and skipped == 1 # the one piece after the last line feed35assert run.ended == "step_cap" and len(records) == CH1.step_cap and records[-1]["stop"] == "step_cap"36assert sum(r["prompt_tokens"] for r in records) == run.prompt_tokens37run.close()
python trace-one-run.py{"arguments":{"path":"unitcraft/format.py"},"brief":"23 lines","calls":["run-0001-c1"],"completion_tokens":22,"gate":[],"malformed":[],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":501,"result":"ok","run":"run-0001","step":1,"stop":"","tool":"read_file"}
{"arguments":{},"brief":"8 failed, 22 passed","calls":["run-0001-c2"],"completion_tokens":70,"gate":[],"malformed":[],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":713,"result":"ok","run":"run-0001","step":2,"stop":"","tool":"run_tests"}
{"arguments":null,"brief":"error: malformed call","calls":["run-0001-c3"],"completion_tokens":560,"gate":[],"malformed":["not JSON (Expecting ',' delimiter)"],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":941,"result":"refused","run":"run-0001","step":3,"stop":"","tool":"malformed"}
{"arguments":null,"brief":"error: malformed call","calls":["run-0001-c4"],"completion_tokens":292,"gate":[],"malformed":["not JSON (Expecting ',' delimiter)"],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":1528,"result":"refused","run":"run-0001","step":4,"stop":"","tool":"malformed"}
{"arguments":null,"brief":"error: malformed call","calls":["run-0001-c5"],"completion_tokens":296,"gate":[],"malformed":["not JSON (Expecting ',' delimiter)"],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":1847,"result":"refused","run":"run-0001","step":5,"stop":"","tool":"malformed"}
{"arguments":null,"brief":"error: malformed call","calls":["run-0001-c6"],"completion_tokens":296,"gate":[],"malformed":["not JSON (Expecting ',' delimiter)"],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":2170,"result":"refused","run":"run-0001","step":6,"stop":"","tool":"malformed"}
{"arguments":null,"brief":"error: malformed call","calls":["run-0001-c7"],"completion_tokens":296,"gate":[],"malformed":["not JSON (Expecting ',' delimiter)"],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":2493,"result":"refused","run":"run-0001","step":7,"stop":"","tool":"malformed"}
{"arguments":null,"brief":"error: malformed call","calls":["run-0001-c8"],"completion_tokens":296,"gate":[],"malformed":["not JSON (Expecting ',' delimiter)"],"offered":["finish","read_file","run_tests"],"parent":null,"prompt_tokens":2816,"result":"refused","run":"run-0001","step":8,"stop":"step_cap","tool":"malformed"}
records: 8
first call ID: run-0001-c1
results: step 1 ok, step 2 ok, step 3 refused, step 4 refused, step 5 refused, step 6 refused, step 7 refused, step 8 refused
prompt tokens, summed over the records: 13009
completion tokens, summed over the records: 2128
blank line: Expecting value: line 1 column 1 (char 0)
lines read back: 8
empty pieces skipped: 1
A execução tem 8 registros, um para cada um dos seus passos, e seu último registro traz a parada, step_cap. Cada registro contém o número do passo, a ferramenta, os argumentos, um resumo de uma linha do que voltou, uma classe de resultado, os IDs de chamada, as ferramentas que foram oferecidas, as linhas do gate para aquele passo e as contagens de tokens daquele passo. O ID da primeira chamada é run-0001-c1.
Os passos seguintes são chamadas malformadas. A resposta do modelo não era JSON válido, então o harness não executou a chamada. Ele registrou o passo como refused e colocou o erro de parse no campo malformed. refused cobre toda chamada que o harness não executou, ou que uma ferramenta recusou antes de rodar: uma resposta que não pode ser analisada ou que foi cortada, um nome de ferramenta que o harness não oferece, argumentos que não se encaixam na ferramenta, uma alteração que um gate retém e um caminho que a verificação própria de uma ferramenta recusa. A terceira classe, error, é diferente. Significa que uma ferramenta foi executada e relatou uma falha. Ler refused como erro de ferramenta leva o leitor a procurar um bug em uma ferramenta que nunca foi chamada.
Somados todos os registros, a execução reproduzida usou 13009 tokens de prompt e 2128 tokens de completion. Esses são os totais que a gravação guardou para cada passo, não contagens feitas durante a reprodução.
O arquivo tem uma armadilha, e o exemplo a mostra no fim. JSON Lines não permite linha em branco, porque uma linha em branco não é um valor. Analisar uma linha vazia falha, e o Python informa isso como Expecting value: line 1 column 1 (char 0). Os registros são gravados em um arquivo e voltam por meio de um leitor. Dividir o texto nos line feeds deixa um pedaço vazio depois do último line feed, então o leitor pula esse pedaço de propósito e o conta. Aqui 8 registros voltam, e 1 pedaço é pulado. Um leitor que não o pulasse pararia no fim de todo arquivo.
Regra prática: Um leitor de trace pula uma linha vazia apenas de propósito, e conta as linhas que pulou. Caso contrário, para na primeira linha vazia. O escritor nunca acrescenta uma linha em branco entre registros.
IDs sem relógios
Um passo de um rastreamento precisa poder ser encontrado novamente, pela execução a que pertence, pela chamada a que responde e pela sua posição na ordem. O rastreamento tira seus IDs de contadores passados pelo chamador, e de mais nenhum lugar. Uma execução é run-0001, numerada a partir de um. Uma chamada de ferramenta é o ID da sua execução com c e um número, de modo que a primeira chamada dessa execução é run-0001-c1, o mesmo ID que o primeiro registro da execução reproduzida carrega. Os passos são numerados a partir de 1, na ordem em que aconteceram.
Nenhum registro carrega um horário. Um carimbo de tempo seria diferente em cada execução, e o mesmo aconteceria com a saída impressa de qualquer exemplo que o mostrasse. Cada exemplo é comparado com a saída que imprimiu quando foi gravado, de modo que um carimbo de tempo falharia nessa comparação em todas as execuções. O rastreamento guarda contagens, resultados curtos e IDs, e nada que venha de um relógio.
Os IDs importam por um segundo motivo. Os IDs de execução e os IDs de chamada entram nos requests que o harness envia ao modelo, de modo que uma reprodução envia o mesmo request da gravação somente quando numera suas execuções do mesmo modo que a gravação as numerou. O código de reprodução de uma tarefa retoma o contador no lugar dessa tarefa na gravação, e é por isso que o exemplo filho numera sua execução pela ordem da gravação, e não a partir do seu próprio início.
Regra prática: Numere execuções e chamadas a partir de um contador passado de fora, nunca a partir de um relógio ou de um gerador aleatório. Um ID que muda entre execuções muda o request, e uma reprodução dessa execução para no primeiro request que não consegue casar com a gravação.
Tokens como contagens
Cada registro no rastro traz duas contagens de tokens, nos tokens do modelo fixado, tal como o capítulo 1 os define. A contagem de prompt é a quantidade de tokens que o modelo leu, e a contagem de conclusão é a quantidade de tokens que ele escreveu. A gravação obtém as duas contagens quando é executada. Ela armazena as contagens de cada etapa junto com a sua resposta, em replies.jsonl, e os totais de cada tarefa no seu manifesto. A reprodução lê as contagens armazenadas e nunca tokeniza de novo, de modo que uma reprodução não pode produzir uma contagem que a gravação não tenha registrado.
Somar as contagens armazenadas de cada etapa, por tarefa e para o conjunto, é a tarefa do próximo exemplo. Ele confere a soma de cada tarefa com os totais que o manifesto armazena para essa tarefa, e confere a soma de prompt do conjunto com a soma desses totais das tarefas.
1"""The token counts of the task-set recording, summed per task and for the set, read from the stored counts. Replay2never tokenizes, so these are the counts the recording wrote; the live check against a tokenizer is not run."""3from lib.models import load_recording4from lib.trace import OTEL_TOKEN_FIELDS56manifest, rows = load_recording("task-set") # rows: one per step, from replies.jsonl; the manifest has task totals7sums: dict[str, list[int]] = {}8for row in rows:9 total = sums.setdefault(row["run"], [0, 0, 0])10 total[0] += row["prompt_tokens"]11 total[1] += row["completion_tokens"]12 total[2] += 1 # each row is one step, so the third sum counts steps13for task in sorted(manifest["tasks"], key=lambda t: t["task"]):14 prompt, completion, steps = sums[task["task"]]15 print(f"{task['task']} prompt tokens: {prompt} completion tokens: {completion} steps: {steps}")16 assert (prompt, completion, steps) == (task["prompt_tokens"], task["completion_tokens"], task["steps"])17set_prompt = sum(total[0] for total in sums.values())18set_completion = sum(total[1] for total in sums.values())19print("set tasks:", len(sums))20print("set prompt tokens:", set_prompt)21print("set completion tokens:", set_completion)22print("live count check: not run")23for field, name in sorted(OTEL_TOKEN_FIELDS.items()): # the mapping table; the book's own names stay in the trace24 print(f"field {field} would map to {name} (data only; OpenTelemetry is not used)")25assert set_prompt == sum(t["prompt_tokens"] for t in manifest["tasks"])
python token-counts-from-recording.pyT-01 prompt tokens: 44836 completion tokens: 2025 steps: 16
T-02 prompt tokens: 43904 completion tokens: 2059 steps: 16
T-03 prompt tokens: 27562 completion tokens: 1463 steps: 12
T-04 prompt tokens: 8809 completion tokens: 1054 steps: 5
T-05 prompt tokens: 8494 completion tokens: 906 steps: 5
T-06 prompt tokens: 55109 completion tokens: 4670 steps: 16
T-07 prompt tokens: 24989 completion tokens: 3468 steps: 9
T-08 prompt tokens: 13713 completion tokens: 1154 steps: 7
T-09 prompt tokens: 10324 completion tokens: 701 steps: 6
T-10 prompt tokens: 51056 completion tokens: 3549 steps: 16
T-11 prompt tokens: 33951 completion tokens: 817 steps: 16
T-12 prompt tokens: 30787 completion tokens: 1617 steps: 12
T-13 prompt tokens: 49249 completion tokens: 942 steps: 16
T-14 prompt tokens: 12651 completion tokens: 972 steps: 7
T-15 prompt tokens: 20409 completion tokens: 1254 steps: 10
T-16 prompt tokens: 57696 completion tokens: 4621 steps: 16
T-17 prompt tokens: 17601 completion tokens: 1511 steps: 9
T-18 prompt tokens: 5122 completion tokens: 304 steps: 4
T-19 prompt tokens: 22713 completion tokens: 2154 steps: 9
T-20 prompt tokens: 33630 completion tokens: 2065 steps: 13
set tasks: 20
set prompt tokens: 572605
set completion tokens: 37306
live count check: not run
field completion_tokens would map to gen_ai.usage.output_tokens (data only; OpenTelemetry is not used)
field prompt_tokens would map to gen_ai.usage.input_tokens (data only; OpenTelemetry is not used)
Todas as somas de tarefas concordam com o manifesto, portanto os totais do conjunto abaixo são as próprias contagens da gravação. O conjunto de tarefas tem 20 tarefas, que juntas usaram 572605 tokens de prompt e 37306 tokens de completion. A verificação de contagem ao vivo da saída, que tokenizaria os prompts gravados com o modelo fixado, informa not run.
O código da biblioteca mostra como uma contagem desse tipo é produzida. O código-fonte do llama-cpp-python foi lido na versão que as gravações fixam, e não foi executado aqui. Suas conclusões sem streaming informam o comprimento da lista de tokens do prompt e da lista de tokens da completion, e a soma dos dois como total (llama.py na versão v0.3.36). Seu método tokenize recebe bytes UTF-8 e devolve uma lista de IDs de tokens inteiros. Ele acrescenta um token de início de sequência, a menos que seja instruído a não o fazer; assim, a contagem de um prompt depende dessa configuração, além do vocabulário do modelo.
Contagens de tokenizers diferentes não são comparáveis. Esta é uma regra prática, não uma medição: um token é uma unidade de um único vocabulário, e o mesmo texto pode se dividir em números diferentes de unidades em outro. O leitor que compara duas contagens deve primeiro verificar que o arquivo do modelo e as configurações coincidem.
O manifesto da gravação armazena o arquivo do modelo e o seu SHA-256, mas não as configurações que moldam a contagem de um prompt: o modelo de chat que a biblioteca aplicou e a configuração do token de início de sequência. A gravação usou os padrões da biblioteca para ambos, e o livro ainda não os registra.
Regra prática: Armazene cada contagem junto ao arquivo de modelo de que veio e a qualquer configuração que a altere, como o token de início de sequência. Não compare contagens de tokenizers diferentes. Uma contagem que nenhuma verificação rederivou é apresentada como contagem armazenada, nunca como contagem ao vivo.
Os registros de um filho ficam sob a chamada do seu pai
O capítulo 8 entrega uma subtarefa a um loop filho e recebe de volta um resumo e um motivo de parada. Ele também mantém o registro próprio do filho junto ao filho, para que o resumo do pai não seja o único rastro do que aconteceu. Esta seção cumpre essa promessa no rastro. Os passos de um filho são gravados como uma execução própria, com ID de execução e IDs de chamada próprios. Cada um dos seus registros traz parent, o ID da chamada que o iniciou. Os registros do filho são impressos logo após a chamada do pai que os iniciou.
Aqui um pai inicia um filho na T-04, uma tarefa que pede uma unidade em polegadas. A execução gravada do filho termina com uma finalização que altera arquivos. Uma pessoa roteirizada recusa essa alteração, então o portão retém a finalização, e o filho devolve o controle com uma pergunta.
1"""A parent starts a child on T-04, whose recorded run ends with a finish that changes files. The gate holds that finish2because the person says no, so the child hands back with ask_user. The child's records sit under the parent's start call;3the parent is scripted, so its records carry zero tokens."""4from lib.case import load_tasks5from lib.chapter1 import call6from lib.models import ReplayModel, load_recording7from lib.permissions import Gate, library_copy, replay_ids, scripted8from lib.subagents import START_CHILD9from lib.tasks import snapshot10from lib.tools import V111from lib.trace import StepRecorder, child_under_parent, dumps1213task = load_tasks(only=["T-04"])[0]14manifest, _ = load_recording("task-set")15stored = next(t for t in manifest["tasks"] if t["task"] == "T-04")16with library_copy() as library:17 before = snapshot(library, "unitcraft")18 gate = Gate(library, scripted((False, "not this change"))) # the scripted person says no, with this reason19 child_model = StepRecorder(ReplayModel("task-set", "T-04"), gate)20 replies = [call(START_CHILD, task_id="T-04"), call("ask_user", question="The child's change was held. Pass it on?")]21 parent, child, records = child_under_parent(task, replies, child_model, gate, library, replay_ids("T-04"))22 for record in records:23 print(dumps(record))24 print("child budget:", V1.step_cap)25 print("child ended:", child.handoff.ended)26 print("gate refusals:", gate.counts["refused"])27 print("parent ended:", parent.ended)28 print("copy unchanged by the held finish:", before == snapshot(library, "unitcraft"))29 child_records = [r for r in records if r["run"] == child.run.id]30 parent_records = [r for r in records if r["run"] != child.run.id]31 print("child run:", child.run.id)32 print("parent call of the child:", child_records[0]["parent"])33 print("held step:", next(r["step"] for r in child_records if r["result"] == "refused"))34 print("parent tokens, summed:", sum(r["prompt_tokens"] + r["completion_tokens"] for r in parent_records))35 child_prompt = sum(r["prompt_tokens"] for r in child_records)36 child_completion = sum(r["completion_tokens"] for r in child_records)37 print("child prompt tokens, summed:", child_prompt)38 print("child completion tokens, summed:", child_completion)39 assert child.handoff.ended == "ask_user" and sum(r["result"] == "refused" for r in records) == 140 assert parent.ended == "ask_user" and before == snapshot(library, "unitcraft")41 assert (child_prompt, child_completion) == (stored["prompt_tokens"], stored["completion_tokens"])42 parent.close()
python child-trace-under-parent.py{"arguments":{"task_id":"T-04"},"brief":"child ask_user at step 5","calls":["run-0001-c1"],"completion_tokens":0,"gate":[],"malformed":[],"offered":["ask_user","start_child"],"parent":null,"prompt_tokens":0,"result":"ok","run":"run-0001","step":1,"stop":"","tool":"start_child"}
{"arguments":{},"brief":"25 files","calls":["run-0004-c1"],"completion_tokens":51,"gate":[],"malformed":[],"offered":["ask_user","edit_file","finish","list_files","read_file","run_tests","write_file"],"parent":"run-0001-c1","prompt_tokens":1049,"result":"ok","run":"run-0004","step":1,"stop":"","tool":"list_files"}
{"arguments":{"path":"unitcraft/units.py"},"brief":"36 lines","calls":["run-0004-c2"],"completion_tokens":108,"gate":[],"malformed":[],"offered":["ask_user","edit_file","finish","list_files","read_file","run_tests","write_file"],"parent":"run-0001-c1","prompt_tokens":1253,"result":"ok","run":"run-0004","step":2,"stop":"","tool":"read_file"}
{"arguments":{"new":"Unit(\"m\", \"length\", Decimal(1)),\n Unit(\"km\", \"length\", Decimal(1000)),\n Unit(\"cm\", \"length\", Decimal(\"0.01\")),\n Unit(\"mm\", \"length\", Decimal(\"0.001\")),\n Unit(\"ft\", \"length\", Decimal(\"0.3048\")),\n Unit(\"in\", \"length\", Decimal(\"0.0254\")),\n Unit(\"kg\", \"mass\", Decimal(1)),\n Unit(\"g\", \"mass\", Decimal(\"0.001\")),\n Unit(\"lb\", \"mass\", Decimal(\"0.45359237\")),\n Unit(\"s\", \"time\", Decimal(1)),\n Unit(\"min\", \"time\", Decimal(60)),\n Unit(\"h\", \"time\", Decimal(3600)),\n Unit(\"C\", \"temperature\", None),\n Unit(\"F\", \"temperature\", None),\n Unit(\"K\", \"temperature\", None),","old":"Unit(\"m\", \"length\", Decimal(1)),\n Unit(\"km\", \"length\", Decimal(1000)),\n Unit(\"cm\", \"length\", Decimal(\"0.01\")),\n Unit(\"mm\", \"length\", Decimal(\"0.001\")),\n Unit(\"ft\", \"length\", Decimal(\"0.3048\")),\n Unit(\"kg\", \"mass\", Decimal(1)),\n Unit(\"g\", \"mass\", Decimal(\"0.001\")),\n Unit(\"lb\", \"mass\", Decimal(\"0.45359237\")),\n Unit(\"s\", \"time\", Decimal(1)),\n Unit(\"min\", \"time\", Decimal(60)),\n Unit(\"h\", \"time\", Decimal(3600)),\n Unit(\"C\", \"temperature\", None),\n Unit(\"F\", \"temperature\", None),\n Unit(\"K\", \"temperature\", None),","path":"unitcraft/units.py"},"brief":"edited unitcraft/units.py","calls":["run-0004-c3"],"completion_tokens":570,"gate":[],"malformed":[],"offered":["ask_user","edit_file","finish","list_files","read_file","run_tests","write_file"],"parent":"run-0001-c1","prompt_tokens":1686,"result":"ok","run":"run-0004","step":3,"stop":"","tool":"edit_file"}
{"arguments":{},"brief":"8 failed, 22 passed","calls":["run-0004-c4"],"completion_tokens":111,"gate":[],"malformed":[],"offered":["ask_user","edit_file","finish","list_files","read_file","run_tests","write_file"],"parent":"run-0001-c1","prompt_tokens":2276,"result":"ok","run":"run-0004","step":4,"stop":"","tool":"run_tests"}
{"arguments":{"summary":"Added the inch unit ('in') with a factor of 0.0254 to the units dictionary in unitcraft/units.py. This allows parse_quantity('2 in') to work correctly and enables the convert function to handle inch-to-meter conversions. The test suite failures indicate other issues in the codebase that are outside the scope of this specific task."},"brief":"p-1 was not applied: the person said no: not this change","calls":["run-0004-c5"],"completion_tokens":214,"gate":["p-1 1 files, diff 06ee73fd984f: asked","p-1 answer no, bound to p-1 and 06ee73fd984f","p-1 not applied: the person said no: not this change"],"malformed":[],"offered":["ask_user","edit_file","finish","list_files","read_file","run_tests","write_file"],"parent":"run-0001-c1","prompt_tokens":2545,"result":"refused","run":"run-0004","step":5,"stop":"ask_user","tool":"finish"}
{"arguments":{"question":"The child's change was held. Pass it on?"},"brief":"ask_user","calls":["run-0001-c2"],"completion_tokens":0,"gate":[],"malformed":[],"offered":["ask_user","start_child"],"parent":null,"prompt_tokens":0,"result":"ok","run":"run-0001","step":2,"stop":"ask_user","tool":"ask_user"}
child budget: 16
child ended: ask_user
gate refusals: 1
parent ended: ask_user
copy unchanged by the held finish: True
child run: run-0004
parent call of the child: run-0001-c1
held step: 5
parent tokens, summed: 0
child prompt tokens, summed: 8809
child completion tokens, summed: 1054
A execução do filho usa o número que a gravação deu à T-04, a quarta execução nela, para que suas requests coincidam com as gravadas. A execução é run-0004, e seu primeiro registro indica a chamada do pai em parent: run-0001-c1.
Os registros do filho trazem as contagens que a gravação armazenou para a T-04, 8809 tokens de prompt e 1054 tokens de completação, que o roteiro confere contra o manifesto. O pai é roteirizado, então seus registros não trazem tokens: 0.
A recusa da pessoa é onde a execução do filho termina. O portão retém a finalização no passo 5, o último registro do filho, e o filho devolve uma pergunta no lugar.
O filho para com ask_user, e o portão recusou 1 chamada. Essa parada vem do portão, e não do orçamento de 16 passos. O pai, que também é roteirizado, faz à pessoa uma pergunta própria e para com ask_user. A cópia da biblioteca permanece inalterada após a execução, que é justamente o objetivo do portão: a alteração retida nunca chegou à biblioteca.
Este exemplo não mostra um filho que esgota o orçamento. O capítulo 8 trata desse caso, e seu motivo de parada vem do orçamento, e não de uma alteração retida.
Regra prática: Dê a cada filho seu próprio ID de execução e seus próprios registros, cada um com parent definido como a chamada que o iniciou. Ao relatar o custo de uma execução do pai, some as contagens dos seus filhos e diga que fez isso. Este rastro as imprime separadamente e não soma nenhuma delas ao pai.
Custo como contagens, não dinheiro
Com as contagens armazenadas somadas por tarefa, o custo de uma execução são três números: seus passos, suas chamadas de ferramenta e seus tokens. Este livro relata esses três e nada além deles. Uma tabela de preços envelhece, e um valor em dólares fica errado após a primeira mudança de preço; por isso, o livro não multiplica suas contagens por um preço. Um leitor que precisa de dólares pode multiplicar as contagens pelo preço que o seu provedor cobra hoje, e os números do livro continuam corretos quando os preços mudam.
Agrupar as contagens armazenadas pelo modo como cada execução terminou coloca as execuções limitadas por passos ao lado das demais, de modo que o custo de cada motivo de parada aparece na mesma saída.
1"""The cost of the task-set runs as counts only: steps, tool calls and tokens, summed per way a run ended. The cost is2tokens, never money, and the tokens are the recording's stored counts; the groups are sorted, so the output is stable."""3from lib.models import load_recording45manifest, rows = load_recording("task-set")6tasks = sorted(manifest["tasks"], key=lambda t: (t["task"], t["kind"]))7for ending in sorted({t["ended"] for t in tasks}):8 group = [t for t in tasks if t["ended"] == ending]9 print(f"ended {ending}: runs {len(group)}, done {sum(t['done'] for t in group)}, "10 f"steps {sum(t['steps'] for t in group)}, tool calls {sum(t['tool_calls'] for t in group)}, "11 f"prompt tokens {sum(t['prompt_tokens'] for t in group)}, "12 f"completion tokens {sum(t['completion_tokens'] for t in group)}")13 print(" tasks:", ", ".join(t["task"] for t in group))14 print(" done:", ", ".join(t["task"] for t in group if t["done"]) or "none")15print(f"all: runs {len(tasks)}, done {sum(t['done'] for t in tasks)}, steps {sum(t['steps'] for t in tasks)}, "16 f"tool calls {sum(t['tool_calls'] for t in tasks)}, prompt tokens {sum(t['prompt_tokens'] for t in tasks)}, "17 f"completion tokens {sum(t['completion_tokens'] for t in tasks)}")18capped = [t for t in tasks if t["ended"] == "step_cap"]19print(f"step-capped runs done: {sum(t['done'] for t in capped)} of {len(capped)}")20print(f"step-capped runs, steps: {sum(t['steps'] for t in capped)} of {sum(t['steps'] for t in tasks)}")21print(f"step-capped runs, prompt tokens: {sum(t['prompt_tokens'] for t in capped)} of "22 f"{sum(t['prompt_tokens'] for t in tasks)}")23prompts: dict[str, list[int]] = {}24for row in sorted(rows, key=lambda r: (r["run"], r["step"])): # the stored step rows, in step order25 prompts.setdefault(row["run"], []).append(row["prompt_tokens"])26rising = [t["task"] for t in capped if all(b > a for a, b in zip(prompts[t["task"]], prompts[t["task"]][1:]))]27print(f"step-capped runs whose prompt count rises at every step: {len(rising)} of {len(capped)}")28assert all(t["tool_calls"] == t["steps"] for t in tasks), "one tool call per step in this recording"
python cost-as-counts.pyended ask_user: runs 7, done 1, steps 69, tool calls 69, prompt tokens 157824, completion tokens 10368
tasks: T-03, T-12, T-15, T-17, T-18, T-19, T-20
done: T-18
ended finish: runs 6, done 4, steps 39, tool calls 39, prompt tokens 78980, completion tokens 8255
tasks: T-04, T-05, T-07, T-08, T-09, T-14
done: T-04, T-05, T-09, T-14
ended step_cap: runs 7, done 0, steps 112, tool calls 112, prompt tokens 335801, completion tokens 18683
tasks: T-01, T-02, T-06, T-10, T-11, T-13, T-16
done: none
all: runs 20, done 5, steps 220, tool calls 220, prompt tokens 572605, completion tokens 37306
step-capped runs done: 0 of 7
step-capped runs, steps: 112 of 220
step-capped runs, prompt tokens: 335801 of 572605
step-capped runs whose prompt count rises at every step: 7 of 7
As execuções limitadas por passos levaram 112 of 220 passos e 335801 of 572605 tokens de prompt. A linha das execuções limitadas por passos traz runs 7, done 0, steps 112, tool calls 112, prompt tokens 335801, completion tokens 18683. A linha de todas as execuções traz runs 20, done 5, steps 220, tool calls 220, prompt tokens 572605, completion tokens 37306, e ela abrange todos os grupos acima dela. Uma asserção adicional verifica a gravação: cada execução fez uma chamada de ferramenta por passo, de modo que as contagens de chamadas de ferramenta e as contagens de passos são o mesmo número.
Nenhuma das execuções limitadas por passos está done: a contagem marca 0 of 7. Uma execução limitada por passos termina sem finish e sem transferência, de modo que o zero decorre da regra de done, quaisquer que sejam os conteúdos dos seus arquivos. O único done do grupo ask_user é T-18, cuja contagem vem de uma correspondência de caminho (capítulo 10). O zero não diz nada sobre quão perto qualquer execução limitada por passos chegou, e este capítulo não o lê como um achado sobre as tarefas.
Julgamento, não medição: a linha das execuções limitadas por passos é o custo de execuções que gastaram seus tokens e não terminaram. Um orçamento de tokens sobre o total de tokens da execução, e não o orçamento de prompt por requisição do capítulo 5, teria interrompido essas execuções mais cedo. O preço disso é a chance de interromper uma execução que teria terminado em um passo posterior, e esta gravação não pode mostrar essa chance, porque cada execução limitada por passos parou no limite e não gravou nenhum passo posterior. A contagem de prompts é o que faz o custo crescer: o laço envia toda a transcrição novamente a cada passo. Contar as execuções limitadas por passos cuja contagem de prompts sobe a cada passo dá 7 of 7. Um orçamento de passos conta passos, de modo que, para uma execução longa, ele diz menos sobre o custo do que os tokens dizem. Se um orçamento de tokens for definido, o harness deve encerrar a execução com seu próprio motivo de parada e suas próprias contagens, para que um corte pelo orçamento possa ser distinguido de um corte pelo limite de passos.
O capítulo 12 compara um agente com um pipeline fixo nessas mesmas unidades, e as unidades só são úteis se toda execução as relatar do mesmo modo.
Regra prática: Relate o custo como os passos, as chamadas de ferramenta e os tokens de cada execução, agrupados pelo modo como terminou, com os grupos impressos lado a lado. Não cite dinheiro. Leia um grupo limitado por passos como tokens gastos sem um done, e não como evidência sobre a tarefa, até que uma segunda medida indique o contrário.
Mantenha seus próprios nomes de campos e faça o mapeamento na fronteira
Os campos de tokens do registro são prompt_tokens e completion_tokens, e são próprios do livro. O projeto OpenTelemetry publica convenções para a telemetria de sistemas de IA generativa. Sua página GenAI spans, na revisão v1.37.0 das convenções semânticas, nomeia as mesmas duas contagens gen_ai.usage.input_tokens e gen_ai.usage.output_tokens (as convenções semânticas, GenAI spans). Nessa revisão, a página indica seu status como "Development", portanto os nomes podem mudar. O livro não usa OpenTelemetry. O exemplo de contagem de tokens exibe os dois nomes ao lado dos campos do livro, apenas como dados, e este capítulo não faz nenhuma afirmação sobre como uma ferramenta do OpenTelemetry lê um trace.
O livro mantém seus próprios nomes por um motivo prático. Um leitor que exporta o trace para outra ferramenta precisa de uma única tabela de mapeamento, e essa tabela é o único lugar que depende do padrão. Os nomes de campos do livro não mudam quando o padrão muda. O mapeamento não acrescenta nada às contagens. A contagem de prompt e a contagem de completion são os mesmos números nos dois conjuntos de nomes, e os registros do trace permanecem como foram escritos.
Regra prática: Dê aos campos do trace nomes que digam o que contam, no seu próprio projeto. Mapeie-os para os nomes de um padrão na fronteira, em uma única tabela, com a revisão do padrão escrita ao lado da tabela. Revise a tabela novamente quando a revisão do padrão mudar.
O que dá errado e como você perceberia
O primeiro erro está no campo result. Uma chamada refused nunca foi executada, e o leitor que toma refused como erro de uma ferramenta procura no lugar errado. Você percebe isso no registro: result é refused, malformed produz o erro de análise, o campo de ferramenta mostra malformed em vez do nome de uma ferramenta, e as linhas do portão estão vazias. A instrução desse passo começa com error:, o que parece falha de uma ferramenta; por isso, leia result e malformed em vez da instrução.
O segundo erro é um carimbo de data e hora, acrescentado para depuração. Ele altera a saída impressa a cada execução, de modo que a comparação do exemplo com a saída registrada falha já na primeira execução após a mudança. A correção é remover o carimbo de data e hora e usar o número do passo. O número do passo é o mesmo em todas as execuções e basta para colocar uma linha em ordem.
O terceiro erro é a linha em branco na primeira seção. Um leitor que passa uma linha vazia a um analisador de JSON falha nela, e a falha parece um arquivo danificado quando o arquivo está correto. Você percebe o problema quando a análise falha com uma string vazia. A correção é uma regra que ignora o trecho vazio de propósito e conta o que foi ignorado, como faz o exemplo.
O quarto erro é tratar o rastro como um controle. Um rastro registra o que o portão e o sandbox decidiram. Ele não decide nada e não pode desfazer uma chamada que foi executada. A finalização retida no exemplo filho foi retida pelo portão, que o capítulo 6 descreve. Os limites sobre comandos vêm do sandbox no capítulo 7. Ler um rastro depois de uma execução ruim informa o que o arcabouço permitiu, e nada além disso.
O quinto ponto é um limite deste capítulo. Ele rastreia apenas as ferramentas integradas. Nenhum servidor MCP é rastreado aqui, portanto este capítulo não afirma nada sobre como as chamadas MCP aparecem em um rastro. O capítulo 9 trata das próprias ferramentas.
Regra prática: Antes de confiar em um rastro para uma decisão, leia seus campos result e stop, depois confira as somas impressas com os totais armazenados. Um rastro que não corresponde aos seus totais tem um erro em quem o escreveu, e a execução que ele registra ainda não é uma conclusão sobre o agente.
O que este capítulo decidiu
- Cada execução grava uma linha JSON por passo, na ordem dos passos, com chaves ordenadas, sem espaços e somente ASCII. Nenhuma linha em branco é gravada.
- Os IDs vêm de contadores recebidos pelo chamador: execuções como
run-0001, chamadas comorun-0001-c1. Nenhum relógio ou valor aleatório entra em um rastro. - As contagens de tokens são as que a gravação armazenou. A verificação de contagem ao vivo não é executada, e o capítulo diz isso onde importa.
- Os registros de um filho trazem o próprio ID de execução e um campo
parent. O custo de um pai inclui as contagens de seus filhos somente quando o relatório diz isso. - O custo é medido em passos, chamadas de ferramenta e tokens, agrupado pelo modo como cada execução terminou. O livro não cita valores monetários.
- Os nomes de campos são do próprio livro. Os nomes do OpenTelemetry são impressos como dados e não são usados.
Um rastro custa uma linha por passo, e em troca responde à pergunta que um motivo de parada não consegue responder: qual passo deu errado, o que o ambiente de execução recusou e quantos tokens cada passo consumiu. O motivo de parada, a pontuação e o custo são tão verificáveis quanto as linhas a partir das quais são contados. Mantenha as linhas, mantenha seus IDs e mantenha as contagens como a gravação as registrou.
Regra prática: Mantenha uma linha por passo, com seus IDs e suas contagens armazenadas, para cada execução que você reportar. Um número que não possa ser rastreado até essas linhas não é reportado.
Este capítulo, nesta edição
Edição 2026.11.2Exemplos aprovados em 20 de nov de 20264 de 4 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.2.