Registra cada ejecución y cuenta lo que costó
Unos 19 minutos de lectura, con 4 ejemplos en 8 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.2. Lee el original
Al terminar este capítulo, podrás hacer que cada ejecución escriba un registro por paso en un archivo que un lector posterior pueda analizar, dar a cada registro identificadores que lo vinculen con su ejecución y con su llamada, y decir cuántos tokens costó la ejecución. Costo aquí significa conteos. Nunca significa dinero.
El agente de mantenimiento realiza sus ejecuciones en unitcraft dentro de una copia de trabajo. Una ejecución puede terminar bien, mal o no terminar, y su motivo de parada solo indica cómo terminó. Toma la ejecución del capítulo 1 sobre T-01, una de las tareas del conjunto de tareas. Lee el archivo correcto y ejecuta las pruebas, y luego hace una cadena de llamadas malformadas hasta llegar al límite de pasos. El motivo de parada dice step_cap, y eso es todo lo que dice. No indica qué tenían en común las llamadas malformadas, qué hizo el arnés con cada una ni cuántos tokens usó cada paso. Esas respuestas están en los pasos, así que el arnés tiene que conservarlos.
El registro de cada paso es la traza. La puntuación del capítulo 10 ya lee los conteos almacenados, y un lector que pregunta por qué se detuvo una ejecución necesita los pasos anteriores a la parada. Este capítulo escribe la traza como datos, da a sus identificadores una forma fija y cuenta lo que contiene. Cada conteo aquí se lee de una grabación o lo imprime un script. Ninguno se toma de un modelo en vivo, así que los conteos son conteos almacenados, y la única comprobación que volvería a derivarlos del modelo no se ha ejecutado.
Una línea por evento
Una traza es un archivo con un objeto JSON por línea. El formato tiene un nombre, JSON Lines, y una definición breve: cada línea contiene un valor JSON, el archivo está en UTF-8 y un salto de línea termina cada línea. La página recomienda un salto de línea después de la última línea, pero no lo exige, y también acepta un retorno de carro y un salto de línea. El formato JSON Lines indica que no se debe incluir una marca de orden de bytes. El arnés escribe cada registro con las claves ordenadas, sin espacios y solo en ASCII, de modo que el mismo registro siempre produce los mismos bytes. Eso importa por la misma razón que importa la salida impresa: un lector puede comparar dos trazas línea por línea.
Reproducir la ejecución del capítulo 1 sobre T-01 escribe sus pasos en esta forma. La reproducción lee la respuesta grabada para cada paso, de modo que la traza es la misma en cada ejecución.
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
La ejecución tiene 8 registros, uno por cada uno de sus pasos, y su último registro lleva la detención, step_cap. Cada registro contiene el número de paso, la herramienta, los argumentos, un resumen de una línea de lo que se devolvió, una clase de resultado, los identificadores de llamada, las herramientas que se ofrecieron, las líneas de la puerta de control para ese paso y los recuentos de tokens de ese paso. El identificador de la primera llamada es run-0001-c1.
Los pasos posteriores son llamadas malformadas. La respuesta del modelo no era JSON válido, así que el arnés no ejecutó la llamada. Registró el paso como refused y puso el error de análisis en el campo malformed. refused abarca toda llamada que el arnés no ejecutó, o que una herramienta rechazó antes de ejecutarla: una respuesta que no se puede analizar o que quedó cortada, un nombre de herramienta que el arnés no ofrece, argumentos que no se ajustan a la herramienta, un cambio que una puerta de control retiene y una ruta que la propia comprobación de la herramienta rechaza. La tercera clase, error, es distinta. Significa que una herramienta se ejecutó e informó de un fallo. Leer refused como un error de herramienta lleva a un lector a buscar un fallo en una herramienta que nunca se llamó.
Sumando los registros, la ejecución reproducida usó 13009 tokens de prompt y 2128 tokens de compleción. Esos son los recuentos que la grabación guardó para cada paso, no recuentos tomados durante la reproducción.
El archivo tiene una trampa, y el ejemplo la muestra al final. JSON Lines no admite una línea en blanco, porque una línea en blanco no es un valor. Analizar una línea vacía falla, y Python lo informa como Expecting value: line 1 column 1 (char 0). Sus registros se guardan en un archivo y vuelven a través de un lector. Dividir el texto por saltos de línea deja una pieza vacía después del último salto de línea, así que el lector omite esa pieza a propósito y la cuenta. Aquí vuelven 8 registros, y se omite 1 pieza. Un lector que no la omitiera se detendría al final de cada archivo.
Regla práctica: Un lector de una traza omite una línea vacía solo a propósito, y cuenta las líneas que omitió. Si no, se detiene en la primera línea vacía. El escritor nunca añade una línea en blanco entre registros.
IDs sin relojes
Un paso de una traza tiene que poder encontrarse de nuevo, por la ejecución a la que pertenece, por la llamada a la que responde y por su lugar en el orden. La traza toma sus IDs de contadores que pasa quien la llama, y de nada más. Una ejecución es run-0001, numerada desde uno. El ID de una llamada a una herramienta es el ID de su ejecución seguido de c y un número, de modo que la primera llamada de esa ejecución es run-0001-c1, el mismo ID que lleva el primer registro de la ejecución reproducida. Los pasos se numeran desde 1 en el orden en que ocurrieron.
Ningún registro lleva una hora. Una marca de tiempo sería distinta en cada ejecución, y lo mismo ocurriría con la salida impresa de cualquier ejemplo que la mostrara. Cada ejemplo se compara con la salida que imprimió cuando se grabó, así que una marca de tiempo fallaría esa comparación en cada ejecución. La traza guarda conteos, resultados breves e IDs, y nada que provenga de un reloj.
Los IDs importan por una segunda razón. Los IDs de ejecución y de llamada se incluyen en las peticiones que el arnés envía al modelo, así que una reproducción envía la misma petición que la grabación solo si numera sus ejecuciones como lo hizo la grabación. El código de reproducción de una tarea toma su contador en el lugar que esa tarea ocupa en la grabación, por eso el ejemplo hijo numera su ejecución según el orden de la grabación y no desde su propio inicio.
Regla práctica: Numera las ejecuciones y las llamadas a partir de un contador que se pasa desde fuera, nunca a partir de un reloj ni de un generador aleatorio. Un ID que cambia entre ejecuciones cambia la petición, y una reproducción de esa ejecución se detiene en la primera petición que no puede hacer coincidir con la grabación.
Recuentos de tokens
Cada registro de la traza lleva dos recuentos de tokens, en los tokens del modelo fijado tal como los define el capítulo 1. El recuento del prompt son los tokens que leyó el modelo, y el recuento de la completación son los tokens que escribió. La grabación toma ambos recuentos al ejecutarse. Guarda los recuentos de cada paso junto a su respuesta, en replies.jsonl, y los totales de cada tarea en su manifiesto. La reproducción lee los recuentos almacenados y nunca vuelve a tokenizar, de modo que una reproducción no puede producir un recuento que la grabación no haya escrito.
Sumar los recuentos almacenados de los pasos por tarea, y para el conjunto, es la tarea del siguiente ejemplo. Comprueba las sumas de cada tarea frente a los totales que el manifiesto almacena para esa tarea, y comprueba que la suma de prompts del conjunto coincida con la suma de los totales de esas tareas.
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)
Las sumas de cada tarea concuerdan con su manifiesto, de modo que los totales del conjunto que aparecen a continuación son los recuentos propios de la grabación. El conjunto de tareas tiene 20 tareas, que en conjunto usaron 572605 tokens de prompt y 37306 tokens de completación. La comprobación de recuento en vivo de la salida, que tokenizaría los prompts grabados con el modelo fijado, informa not run.
El código fuente de la biblioteca muestra cómo se produce un recuento de este tipo. Se leyó el código fuente de llama-cpp-python en la versión que fijan las grabaciones, y no se ejecutó aquí. Sus completaciones no transmitidas informan la longitud de la lista de tokens del prompt y de la lista de tokens de la completación, y su suma como total (llama.py en v0.3.36). Su método tokenize toma bytes UTF-8 y devuelve una lista de identificadores de token enteros. Añade un token de inicio de secuencia a menos que se le indique lo contrario, de modo que el recuento de un prompt depende de ese ajuste además del vocabulario del modelo.
Los recuentos de tokenizers distintos no son comparables. Esto es una regla práctica, no una medición: un token es una unidad de un vocabulario, y el mismo texto puede dividirse en un número distinto de unidades con otro. Un lector que compare dos recuentos debe comprobar primero que el archivo del modelo y los ajustes coinciden.
El manifiesto de la grabación almacena el archivo del modelo y su SHA-256, pero no los ajustes que determinan el recuento de un prompt: la plantilla de chat que aplicó la biblioteca y el ajuste de token de inicio de secuencia. La grabación usó los valores por defecto de la biblioteca para ambos, y el libro todavía no los escribe.
Regla práctica: Guarda cada recuento junto al archivo del modelo del que procede y junto a cualquier ajuste que lo cambie, como el token de inicio de secuencia. No compares recuentos de tokenizers distintos. Un recuento que ninguna comprobación haya vuelto a derivar se informa como recuento almacenado, nunca como recuento en vivo.
Los registros de un hijo quedan bajo la llamada de su padre
Capítulo 8 entrega una subtarea a un bucle hijo y recibe a cambio un resumen y un motivo de parada. También conserva el registro propio del hijo junto a él, de modo que el resumen del padre no sea el único rastro de lo que ocurrió. Esta sección cumple esa promesa en la traza. Los pasos de un hijo se escriben como su propia ejecución, con su propio ID de ejecución y sus propios ID de llamada. Cada uno de sus registros lleva parent, el ID de la llamada que lo inició. Los registros del hijo se imprimen justo después de la llamada del padre que los inició.
Aquí un padre inicia un hijo en T-04, una tarea que pide una unidad en pulgadas. La ejecución registrada del hijo termina con un cierre que cambia archivos. Una persona programada dice que no a ese cambio, así que la puerta retiene el cierre y el hijo devuelve el control con una pregunta.
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
La ejecución del hijo toma el número que la grabación dio a T-04, la cuarta ejecución de la grabación, de modo que sus peticiones coinciden con las grabadas. La ejecución es run-0004, y su primer registro nombra la llamada del padre en parent: run-0001-c1.
Los registros del hijo llevan los recuentos que la grabación guardó para T-04, 8809 tokens de entrada y 1054 tokens de salida, que el script verifica frente al manifiesto. El padre está programado, así que sus registros no llevan tokens: 0.
El no de la persona es donde termina la ejecución del hijo. La puerta retiene el cierre en el paso 5, el último registro del hijo, y el hijo devuelve una pregunta en su lugar.
El hijo se detiene con ask_user, y la puerta rechazó 1 llamada. Esa parada proviene de la puerta, no del presupuesto de 16 pasos. El padre, que también está programado, hace a la persona una pregunta propia y se detiene con ask_user. La copia de la biblioteca no cambia después de la ejecución, que es el objetivo central de la puerta: el cambio retenido nunca llegó a la biblioteca.
Este ejemplo no muestra un hijo que se queda sin presupuesto. Capítulo 8 trata ese caso, y su motivo de parada proviene del presupuesto, no de un cambio retenido.
Regla práctica: Da a cada hijo su propio ID de ejecución y sus propios registros, cada uno con parent igual a la llamada que lo inició. Cuando informes lo que costó una ejecución del padre, suma los recuentos de sus hijos y di que lo hiciste. Esta traza los imprime por separado y no suma ninguno dentro del padre.
Costo como conteos, no como dinero
Con los conteos almacenados sumados por tarea, el costo de una ejecución son tres números: sus pasos, sus llamadas a herramientas y sus tokens. Este libro informa esos tres y nada más. Una tabla de precios envejece, y una cifra en dólares queda equivocada después del primer cambio de precio, así que el libro no multiplica sus conteos por un precio. Si necesitas dólares, puedes multiplicar los conteos por el precio que su proveedor cobra hoy, y las cifras del libro siguen siendo correctas cuando cambian los precios.
Agrupar los conteos almacenados según cómo terminó cada ejecución pone las ejecuciones limitadas por pasos junto a las demás, de modo que el costo de cada motivo de parada se muestra en la misma salida.
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
Las ejecuciones limitadas por pasos tomaron 112 of 220 pasos y 335801 of 572605 tokens de prompt. La línea de las ejecuciones limitadas por pasos dice runs 7, done 0, steps 112, tool calls 112, prompt tokens 335801, completion tokens 18683. La línea de todas las ejecuciones dice runs 20, done 5, steps 220, tool calls 220, prompt tokens 572605, completion tokens 37306, y abarca todos los grupos de arriba. Una aserción adicional comprueba el registro: cada ejecución hizo una llamada a herramienta por paso, así que los conteos de llamadas a herramientas y los conteos de pasos son el mismo número.
Ninguna de las ejecuciones limitadas por pasos está terminada: el conteo dice 0 of 7. Una ejecución limitada por pasos termina sin finish ni traspaso, así que el cero se sigue de la regla de terminado sin importar lo que contengan sus archivos. El único terminado del grupo de ask_user, T-18, llega por una coincidencia de ruta (capítulo 10). El cero no dice qué tan cerca estuvo ninguna ejecución limitada por pasos de terminar, y este capítulo no lo lee como un hallazgo sobre las tareas.
Juicio, no medición: la línea de las limitadas por pasos es el costo de las ejecuciones que gastaron sus tokens y no terminaron. Un presupuesto de tokens sobre el total de la ejecución, no el presupuesto de prompt por solicitud del capítulo 5, habría detenido esas ejecuciones antes. Su precio es la posibilidad de detener una ejecución que habría terminado en un paso posterior, y este registro no puede mostrar esa posibilidad, porque cada ejecución limitada por pasos se detuvo en el tope y no escribió ningún paso posterior. El conteo de prompt es lo que hace crecer el costo: el bucle vuelve a enviar toda la transcripción en cada paso. Contar las ejecuciones limitadas por pasos cuyo conteo de prompt sube en cada paso da 7 of 7. Un presupuesto de pasos cuenta pasos, así que en una ejecución larga dice menos sobre el costo que los tokens. Si se fija un presupuesto de tokens, el arnés debería terminar la ejecución con su propio motivo de parada y sus propios conteos, para que un corte por el presupuesto pueda distinguirse de un corte por el tope de pasos.
El capítulo 12 compara un agente con una canalización fija en estas mismas unidades, y las unidades solo sirven si cada ejecución las informa de la misma manera.
Regla práctica: Informa el costo como los pasos, llamadas a herramientas y tokens de cada ejecución, agrupados según cómo terminó, con los grupos impresos uno junto a otro. No indiques cifras de dinero. Lee un grupo limitado por pasos como tokens gastados sin terminar, y no como evidencia sobre la tarea hasta que una segunda medida diga otra cosa.
Conserva tus propios nombres de campo y haz la correspondencia en el borde
Los campos de tokens del registro son prompt_tokens y completion_tokens, y son propios del libro. El proyecto OpenTelemetry publica convenciones para la telemetría de sistemas de IA generativa. Su página de spans de GenAI, en la revisión v1.37.0 de las convenciones semánticas, nombra los mismos dos conteos gen_ai.usage.input_tokens y gen_ai.usage.output_tokens (las convenciones semánticas, spans de GenAI). En esa revisión la página indica su estado como "Development", así que los nombres pueden cambiar. El libro no usa OpenTelemetry. El ejemplo de conteo de tokens muestra los dos nombres junto a los campos del libro, solo como datos, y este capítulo no afirma nada sobre cómo una herramienta de OpenTelemetry lee una traza.
El libro conserva sus propios nombres por una razón práctica. Quien exporta la traza a otra herramienta necesita una sola tabla de correspondencia, y esa tabla es el único lugar que depende del estándar. Los nombres de campo del libro no cambian cuando cambia el estándar. La correspondencia no añade nada a los conteos. El conteo de prompt y el conteo de completado son los mismos números con ambos conjuntos de nombres, y los registros de la traza permanecen como se escribieron.
Regla práctica: Nombra los campos de la traza según lo que cuentan, en tu propio proyecto. Haz la correspondencia con los nombres de un estándar en el borde, en una sola tabla, con la revisión del estándar escrita junto a la tabla. Vuelve a revisar la tabla cuando cambie la revisión del estándar.
Qué sale mal y cómo lo notarías
El primer error está en el campo result. Una llamada a refused nunca se ejecutó, y un lector que toma refused por un error de una herramienta busca en el lugar equivocado. Lo notas en el registro: result es refused, malformed indica el error de análisis, el campo de herramienta muestra malformed en lugar del nombre de una herramienta, y las líneas de la compuerta están vacías. El resumen de un paso así empieza con error:, que parece un fallo de una herramienta, así que lee result y malformed en lugar del resumen.
El segundo error es una marca de tiempo, añadida para depurar. Cambia la salida impresa en cada ejecución, así que la comparación del ejemplo con su salida registrada falla en la primera ejecución después del cambio. La solución es quitar la marca de tiempo y usar el número de paso. El número de paso es el mismo en cada ejecución, y basta para poner una línea en orden.
El tercer error es la línea en blanco de la primera sección. Un lector que pasa una línea vacía a un analizador de JSON falla con ella, y el fallo parece un archivo dañado cuando el archivo está bien. Lo notas cuando el análisis falla con una cadena vacía. La solución es una regla que omite a propósito el fragmento vacío y cuenta la omisión, como hace el ejemplo.
El cuarto error es tratar la traza como un control. Una traza registra lo que decidieron la compuerta y el entorno aislado. No decide nada, y no puede deshacer una llamada que ya se ejecutó. La finalización retenida en el ejemplo del hijo la retuvo la compuerta, que describe el capítulo 6. Los límites de los comandos vienen del entorno aislado en el capítulo 7. Leer una traza después de una mala ejecución te dice qué permitió el arnés, y nada más.
El quinto punto es un límite de este capítulo. Traza solo las herramientas integradas. Aquí no se traza ningún servidor MCP, así que este capítulo no afirma nada sobre cómo aparecen las llamadas MCP en una traza. El capítulo 9 trata las herramientas en sí.
Regla práctica: Antes de confiar en una traza para tomar una decisión, lee sus campos result y stop, y luego comprueba sus sumas impresas frente a los totales almacenados. Una traza que no coincide con sus totales tiene un error en su escritor, y la ejecución que registra todavía no es un hallazgo sobre el agente.
Lo que decidió este capítulo
- Cada ejecución escribe una línea JSON por paso, en orden de pasos, con las claves ordenadas, sin espacios y solo en ASCII. No se escribe ninguna línea en blanco.
- Los identificadores provienen de contadores que pasa quien llama: las ejecuciones como
run-0001, las llamadas comorun-0001-c1. Ningún reloj ni valor aleatorio entra en una traza. - Los recuentos de tokens son los que guardó la grabación. La comprobación en vivo del recuento no se ejecuta, y el capítulo lo indica donde importa.
- Los registros de un hijo llevan su propio identificador de ejecución y un campo
parent. El coste de un padre incluye los recuentos de sus hijos solo cuando el informe lo indica. - El coste son los pasos, las llamadas a herramientas y los tokens, agrupados según cómo terminó cada ejecución. El libro no cita ningún importe en dinero.
- Los nombres de campo del libro son los suyos propios. Los nombres de OpenTelemetry se imprimen como datos y no se usan.
Una traza cuesta una línea por paso y permite obtener la respuesta a la pregunta que un motivo de parada no puede responder: qué paso falló, qué rechazó el arnés y cuántos tokens consumió cada paso. El motivo de parada, la puntuación y el coste solo son tan verificables como las líneas a partir de las que se cuentan. Conserva las líneas, conserva sus identificadores y conserva los recuentos tal como los escribió la grabación.
Regla práctica: Conserva una línea por paso, con sus identificadores y sus recuentos almacenados, para cada ejecución que reportes. Una cifra que no pueda rastrearse hasta esas líneas no se informa.
Este capítulo, en esta edición
Edición 2026.11.2Ejemplos verificados el 20 de nov de 2026Superan la prueba 4 de 4 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.2.