各実行をトレースし、そのコストを数える

読了まで約29 分分、8 節 節の 4 例 例。

第2026.11.2版 2026年11月20日時点で例が通過 64 例中 64 例が合格 変更点

AIによる翻訳。英語版は人による検証済みである。 当社の書籍の作り方

英語版の書籍(版2026.11.2)から翻訳した。 原文を読む

この章を終えると、次のことができるようになる。各実行について、後から読み手が解析できる形式で、1ステップにつき1件のレコードをファイルに書き出す。各レコードに、その実行と呼び出しとを結び付けるIDを付ける。実行にかかったコストをトークン数で表す。ここでのコストとは数のことであり、金額のことではない。

保守エージェントは、unitcraft 上の作業用コピーで実行を行う。実行は、うまく終わることも、失敗に終わることも、終わらないこともある。停止理由が示すのは、どのように終わったかだけである。第1章の、タスクセットのタスクの一つであるT-01での実行を例に取る。この実行は、正しいファイルを読み、テストを実行した後、ステップ上限に達するまで不正な呼び出しを続ける。停止理由は step_cap となるが、停止理由が示すのはそれだけである。不正な呼び出しに共通していた点は何か、ハーネスがそれぞれの呼び出しをどう扱ったか、各ステップで何トークンを使ったかは、停止理由からは分からない。これらの答えはステップの中にあるため、ハーネスはステップを保存しておかなければならない。

各ステップの記録がトレースである。第10章のスコアはすでに保存済みの数を読んでおり、実行がなぜ止まったのかを知りたい読み手には、停止に至るまでのステップが必要になる。この章では、トレースをデータとして書き出し、そのIDに固定の形式を与え、トレースに含まれるものを数える。ここでの数はすべて、記録から読み取ったものか、スクリプトが出力したものである。実際のモデルから得たものは一つもない。したがってこれらの数は保存された数であり、モデルから数を導き直す検証は実施していない。

1イベント1行

トレースは、1行に1つの JSON オブジェクトを置いたファイルである。この形式には JSON Lines という名前があり、定義は短い。各行は1つの JSON 値を保持し、ファイルは UTF-8 で書かれ、各行は改行(line feed)で終わる。同ページは最終行の後にも改行を置くことを推奨しているが、必須とはしていない。また、キャリッジリターンと改行の組も受け付ける。JSON Lines format は、バイトオーダーマークを含めてはならないと定めている。ハーネスは各レコードをキーをソートし、空白を入れず、ASCII のみで書き出す。そのため、同じレコードは常に同じバイト列になる。これは出力の表示が重要であるのと同じ理由で重要である。読み手が2つのトレースを行単位で比較できるからである。

T-01 で1章の実行をリプレイすると、そのステップがこの形式で書き出される。リプレイは各ステップについて記録済みの応答を読み込むので、トレースは実行のたびに同一になる。

trace-one-run.py Python 3.12.15 · pydantic 2.14.3 合格
"""The chapter 1 recorded run of T-01 as JSON lines: one record per step, with run-scoped IDs and the recorded tokencounts. The lines are written to a file and read back, and the reader counts the empty pieces it skips."""import jsonimport tempfilefrom pathlib import Pathfrom lib.case import load_tasksfrom lib.loop import run_taskfrom lib.models import ReplayModelfrom lib.tools import CH1from lib.trace import IdCounter, StepRecorder, dumps, read_lines, step_recordstask = load_tasks(only=["T-01"])[0]model = StepRecorder(ReplayModel("chapter-1-t01", "T-01"))run = run_task(model, task, CH1, max_steps=CH1.step_cap, ids=IdCounter())records = step_records(run, model)for record in records:    print(dumps(record))print("records:", len(records))print("first call ID:", records[0]["calls"][0])print("results:", ", ".join(f"step {r['step']} {r['result']}" for r in records))print("prompt tokens, summed over the records:", sum(r["prompt_tokens"] for r in records))print("completion tokens, summed over the records:", sum(r["completion_tokens"] for r in records))try:    json.loads("")  # a blank line is not a JSON valueexcept json.JSONDecodeError as error:    print("blank line:", error)with tempfile.TemporaryDirectory() as folder:    path = Path(folder) / "trace.jsonl"    path.write_text("".join(dumps(record) + "\n" for record in records), encoding="utf-8")    read_back, skipped = read_lines(path.read_text(encoding="utf-8"))print("lines read back:", len(read_back))print("empty pieces skipped:", skipped)assert read_back == records and skipped == 1  # the one piece after the last line feedassert run.ended == "step_cap" and len(records) == CH1.step_cap and records[-1]["stop"] == "step_cap"assert sum(r["prompt_tokens"] for r in records) == run.prompt_tokensrun.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

この実行には 8 件のレコードがあり、ステップごとに1件ずつである。最後のレコードには停止理由 step_cap が入っている。各レコードは、ステップ番号、ツール、引数、返ってきた内容の1行要約、結果クラス、呼び出し ID、提示されたツール、そのステップに対するゲートの行、そのステップのトークン数を保持する。最初の呼び出しの ID は run-0001-c1 である。

後のほうのステップは不正な形式の呼び出しである。モデルの応答が有効な JSON ではなかったため、ハーネスは呼び出しを実行しなかった。ハーネスはそのステップを refused として記録し、パースエラーを malformed フィールドに入れた。refused は、ハーネスが実行しなかった呼び出し、またはツールが実行前に拒否した呼び出しのすべてを対象とする。具体的には、パースできない応答や途中で切れた応答、ハーネスが提供しないツール名、ツールに合わない引数、ゲートが保留する変更、ツール自身の検査が拒否するパスである。3つ目のクラス error は異なる。これは、ツールが実行され、失敗を報告したことを意味する。refused をツールのエラーと読むと、読み手は一度も呼ばれていないツールのバグを探すことになる。

レコード全体で合計すると、リプレイされた実行はプロンプトトークン 13009 個、補完トークン 2128 個を使った。これらは記録が各ステップについて保存していた数であり、リプレイ中に計測した数ではない。

このファイルには罠が1つあり、例の末尾がそれを示している。JSON Lines は空行を許さない。空行は値ではないからである。空行のパースは失敗し、Python はそれを Expecting value: line 1 column 1 (char 0) と報告する。例のレコードはファイルに書き出され、リーダーを通して読み戻される。テキストを改行で分割すると、最後の改行の後に空の断片が1つ残る。そのためリーダーはその断片を意図的に読み飛ばし、読み飛ばした数を数える。ここでは 8 件のレコードが読み戻され、1 個の断片が読み飛ばされる。これを読み飛ばさないリーダーは、あらゆるファイルの末尾で止まってしまう。

実践ルール: トレースのリーダーは、空行を意図的な場合にのみ読み飛ばし、読み飛ばした行数を数える。そうしなければ、最初の空行で止まってしまう。ライターはレコードの間に空行を決して入れない。

時計を使わないID

トレースの中のステップは、属するランによって、応答する呼び出しによって、また順序上の位置によって、あとから見つけ出せなければならない。トレースのIDは、呼び出し側から渡されるカウンタからのみ作り、ほかからは作らない。ランは run-0001 のように1から番号を振る。ツール呼び出しのIDは、そのランのIDに c と番号を付けたものであり、そのランの最初の呼び出しは run-0001-c1 になる。これは、再生されたランの最初のレコードが持つIDと同じである。ステップは、起きた順に1から番号を振る。

どのレコードにも時刻は含めない。タイムスタンプは実行のたびに異なり、それを表示する例の出力も実行のたびに異なってしまう。各例は、記録されたときに出力した内容と比較される。したがって、タイムスタンプがあると、その比較は実行のたびに失敗する。トレースが保持するのは、件数、短い結果、IDだけであり、時計に由来するものは何も含まない。

IDが重要である理由はもう一つある。ランIDと呼び出しIDは、ハーネスがモデルに送るrequestsに含まれる。そのため、再生が記録と同じリクエストを送るのは、記録のときと同じ方法でランに番号を振った場合に限られる。タスクの再生コードは、記録の中でそのタスクが占める位置からカウンタを引き継ぐ。子の例が、自身の開始時点からではなく、記録の順序に従ってランの番号を決めるのはこのためである。

実践ルール: ランと呼び出しには、渡されたカウンタから番号を振る。時計や乱数生成器から振ってはならない。実行のたびに変わるIDはリクエストを変えてしまい、そのランの再生は、記録と照合できない最初のリクエストで止まる。

数としてのトークン

トレースの各レコードは、2 つのトークン数を持つ。トークンは、第 1 章が定義する、固定したモデルのトークンである。プロンプト数はモデルが読んだトークンの数であり、完了数はモデルが書いたトークンの数である。記録は実行時に両方の数を取得する。記録は各ステップの数をその応答とともにreplies.jsonlに保存し、各タスクの合計をそのマニフェストに保存する。再生は保存された数を読むだけで、再びトークン化することはない。したがって、再生は、記録が書き込んでいない数を生み出すことができない。

タスクごとおよびタスク集合全体で、保存されたステップ数を合計するのが、次の例の役割である。この例は、各タスクの合計を、マニフェストがそのタスクについて保存している合計と照合する。また、集合のプロンプト合計を、それらのタスク合計の和と照合する。

token-counts-from-recording.py Python 3.12.15 合格
"""The token counts of the task-set recording, summed per task and for the set, read from the stored counts. Replaynever tokenizes, so these are the counts the recording wrote; the live check against a tokenizer is not run."""from lib.models import load_recordingfrom lib.trace import OTEL_TOKEN_FIELDSmanifest, rows = load_recording("task-set")  # rows: one per step, from replies.jsonl; the manifest has task totalssums: dict[str, list[int]] = {}for row in rows:    total = sums.setdefault(row["run"], [0, 0, 0])    total[0] += row["prompt_tokens"]    total[1] += row["completion_tokens"]    total[2] += 1  # each row is one step, so the third sum counts stepsfor task in sorted(manifest["tasks"], key=lambda t: t["task"]):    prompt, completion, steps = sums[task["task"]]    print(f"{task['task']} prompt tokens: {prompt} completion tokens: {completion} steps: {steps}")    assert (prompt, completion, steps) == (task["prompt_tokens"], task["completion_tokens"], task["steps"])set_prompt = sum(total[0] for total in sums.values())set_completion = sum(total[1] for total in sums.values())print("set tasks:", len(sums))print("set prompt tokens:", set_prompt)print("set completion tokens:", set_completion)print("live count check: not run")for field, name in sorted(OTEL_TOKEN_FIELDS.items()):  # the mapping table; the book's own names stay in the trace    print(f"field {field} would map to {name} (data only; OpenTelemetry is not used)")assert set_prompt == sum(t["prompt_tokens"] for t in manifest["tasks"])
出力python token-counts-from-recording.py
T-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)

すべてのタスクの合計がマニフェストと一致しているので、以下の集合の合計は記録自身の数である。タスク集合には20個のタスクがあり、合わせて572605個のプロンプトトークンと37306個の完了トークンを使用した。出力のライブ数の検査は、記録されたプロンプトを固定したモデルでトークン化するものであり、その結果はnot runと報告される。

この種の数がどのように生成されるかは、ライブラリのソースから分かる。llama-cpp-python のソースは、記録が固定しているリリースで読んだものであり、ここでは実行していない。ストリーミングを使わない補完は、プロンプトのトークン列の長さと補完のトークン列の長さを報告し、その和を合計として報告する(llama.py at v0.3.36)。tokenizeメソッドは UTF-8 のバイト列を受け取り、整数のトークン ID のリストを返す。付加しないよう指示されない限り、先頭トークン(beginning-of-sequence token)を付加するので、プロンプトの数はモデルの語彙だけでなく、この設定にも依存する。

異なるトークナイザーの数は比較できない。これは測定ではなく経験則である。トークンは 1 つの語彙の単位であり、同じテキストでも別の語彙では異なる数の単位に分割されうる。2 つの数を比較する読者は、まずモデルファイルと設定が一致していることを確認しなければならない。

記録のマニフェストは、モデルファイルとその SHA-256 を保存しているが、プロンプトの数を左右する設定は保存していない。その設定とは、ライブラリが適用したチャットテンプレートと、先頭トークンの設定である。記録は両方についてライブラリの既定値を使用したが、本書はまだそれらを書き記していない。

実践ルール: 各数は、それを得たモデルファイルとともに、またそれを変える設定(先頭トークンなど)とともに保存する。異なるトークナイザーの数を比較してはならない。どの検査も再導出していない数は、保存された数として報告し、ライブの数として報告してはならない。

子の記録は親の呼び出しの下に置かれる

第8章では、サブタスクを子ループに渡し、要約と停止理由を受け取る。あわせて、子自身の記録も子のもとに保持する。そのため、親の要約だけが何が起きたかを示す唯一の痕跡にはならない。本節では、この約束をトレースの中で果たす。子のステップは、独自の実行 ID と独自の呼び出し ID を持つ別個の実行として書き込まれる。子の各記録は、その子を開始した呼び出しの ID である parent を持つ。子の記録は、それを開始した親の呼び出しの直後にそのまま出力される。

ここでは、親が T-04 に対して子を開始する。T-04 はインチ単位を求めるタスクである。子の記録された実行は、ファイルを変更する finish で終わる。スクリプトで動く人がその変更を拒否するため、ゲートは finish を保留し、子は質問を添えて引き返す。

child-trace-under-parent.py Python 3.12.15 · pydantic 2.14.3 合格
"""A parent starts a child on T-04, whose recorded run ends with a finish that changes files. The gate holds that finishbecause the person says no, so the child hands back with ask_user. The child's records sit under the parent's start call;the parent is scripted, so its records carry zero tokens."""from lib.case import load_tasksfrom lib.chapter1 import callfrom lib.models import ReplayModel, load_recordingfrom lib.permissions import Gate, library_copy, replay_ids, scriptedfrom lib.subagents import START_CHILDfrom lib.tasks import snapshotfrom lib.tools import V1from lib.trace import StepRecorder, child_under_parent, dumpstask = load_tasks(only=["T-04"])[0]manifest, _ = load_recording("task-set")stored = next(t for t in manifest["tasks"] if t["task"] == "T-04")with library_copy() as library:    before = snapshot(library, "unitcraft")    gate = Gate(library, scripted((False, "not this change")))  # the scripted person says no, with this reason    child_model = StepRecorder(ReplayModel("task-set", "T-04"), gate)    replies = [call(START_CHILD, task_id="T-04"), call("ask_user", question="The child's change was held. Pass it on?")]    parent, child, records = child_under_parent(task, replies, child_model, gate, library, replay_ids("T-04"))    for record in records:        print(dumps(record))    print("child budget:", V1.step_cap)    print("child ended:", child.handoff.ended)    print("gate refusals:", gate.counts["refused"])    print("parent ended:", parent.ended)    print("copy unchanged by the held finish:", before == snapshot(library, "unitcraft"))    child_records = [r for r in records if r["run"] == child.run.id]    parent_records = [r for r in records if r["run"] != child.run.id]    print("child run:", child.run.id)    print("parent call of the child:", child_records[0]["parent"])    print("held step:", next(r["step"] for r in child_records if r["result"] == "refused"))    print("parent tokens, summed:", sum(r["prompt_tokens"] + r["completion_tokens"] for r in parent_records))    child_prompt = sum(r["prompt_tokens"] for r in child_records)    child_completion = sum(r["completion_tokens"] for r in child_records)    print("child prompt tokens, summed:", child_prompt)    print("child completion tokens, summed:", child_completion)    assert child.handoff.ended == "ask_user" and sum(r["result"] == "refused" for r in records) == 1    assert parent.ended == "ask_user" and before == snapshot(library, "unitcraft")    assert (child_prompt, child_completion) == (stored["prompt_tokens"], stored["completion_tokens"])    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

子の実行には、記録が T-04 に割り当てた番号、すなわち記録内の 4 番目の実行が使われる。そのため、子のリクエストは記録されたものと一致する。この実行は run-0004 であり、最初の記録は parent で親の呼び出しを指している。その値は run-0001-c1 である。

子の記録は、T-04 について記録に保存されていた件数を持つ。プロンプトトークンは 8809、完了トークンは 1054 であり、スクリプトはこれらをマニフェストと照合して検証する。親はスクリプトで動くため、その記録にトークンはない。合計は 0 である。

人の拒否によって、子の実行は終わる。ゲートはステップ 5 で finish を保留する。これが子の最後の記録であり、子は代わりに質問を返して引き返す。

子は ask_user で停止し、ゲートが拒否した呼び出しは 1 件である。この停止の原因はゲートであり、16 ステップという予算ではない。同じくスクリプトで動く親は、自分の質問を人に投げかけ、ask_user で停止する。実行後もライブラリのコピーは変更されていない。これがゲートの要点であり、保留された変更はライブラリに届かなかった。

この例では、予算を使い切る子は示さない。そのケースは第8章で扱う。その停止理由は、保留された変更ではなく予算から生じる。

実践ルール: 子ごとに独自の実行 ID と独自の記録を与え、各記録の parent には、その子を開始した呼び出しを設定する。親の実行のコストを報告するときは、子の件数を加算し、加算したことを明記する。このトレースでは、子の件数を別々に出力し、親には一切合算していない。

コストは金額ではなく回数で表す

タスクごとに合計した保存済みの回数を用いると、1回の実行のコストはステップ数、ツール呼び出し数、トークン数の三つの数で表される。本書が報告するのはこの三つだけである。価格表はやがて古くなり、ドル建ての数値は最初の価格改定の後も誤ったまま残る。そのため本書は、回数に価格を掛けることをしない。金額が必要な読者は、利用している提供元が現在請求している価格を回数に掛ければよい。そうすれば、価格が変わっても本書の数値は正しいままである。

保存済みの回数を各実行の終了のしかたでグループ化すると、ステップ上限で終了した実行がほかの実行と並ぶ。そのため、終了理由ごとのコストが同じ出力に表れる。

cost-as-counts.py Python 3.12.15 合格
"""The cost of the task-set runs as counts only: steps, tool calls and tokens, summed per way a run ended. The cost istokens, never money, and the tokens are the recording's stored counts; the groups are sorted, so the output is stable."""from lib.models import load_recordingmanifest, rows = load_recording("task-set")tasks = sorted(manifest["tasks"], key=lambda t: (t["task"], t["kind"]))for ending in sorted({t["ended"] for t in tasks}):    group = [t for t in tasks if t["ended"] == ending]    print(f"ended {ending}: runs {len(group)}, done {sum(t['done'] for t in group)}, "          f"steps {sum(t['steps'] for t in group)}, tool calls {sum(t['tool_calls'] for t in group)}, "          f"prompt tokens {sum(t['prompt_tokens'] for t in group)}, "          f"completion tokens {sum(t['completion_tokens'] for t in group)}")    print("  tasks:", ", ".join(t["task"] for t in group))    print("  done:", ", ".join(t["task"] for t in group if t["done"]) or "none")print(f"all: runs {len(tasks)}, done {sum(t['done'] for t in tasks)}, steps {sum(t['steps'] for t in tasks)}, "      f"tool calls {sum(t['tool_calls'] for t in tasks)}, prompt tokens {sum(t['prompt_tokens'] for t in tasks)}, "      f"completion tokens {sum(t['completion_tokens'] for t in tasks)}")capped = [t for t in tasks if t["ended"] == "step_cap"]print(f"step-capped runs done: {sum(t['done'] for t in capped)} of {len(capped)}")print(f"step-capped runs, steps: {sum(t['steps'] for t in capped)} of {sum(t['steps'] for t in tasks)}")print(f"step-capped runs, prompt tokens: {sum(t['prompt_tokens'] for t in capped)} of "      f"{sum(t['prompt_tokens'] for t in tasks)}")prompts: dict[str, list[int]] = {}for row in sorted(rows, key=lambda r: (r["run"], r["step"])):  # the stored step rows, in step order    prompts.setdefault(row["run"], []).append(row["prompt_tokens"])rising = [t["task"] for t in capped if all(b > a for a, b in zip(prompts[t["task"]], prompts[t["task"]][1:]))]print(f"step-capped runs whose prompt count rises at every step: {len(rising)} of {len(capped)}")assert all(t["tool_calls"] == t["steps"] for t in tasks), "one tool call per step in this recording"
出力python cost-as-counts.py
ended 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

ステップ上限で終了した実行は、112 of 220 ステップと 335801 of 572605 プロンプトトークンを要した。ステップ上限で終了した実行の行は runs 7, done 0, steps 112, tool calls 112, prompt tokens 335801, completion tokens 18683 と表示される。すべての実行の行は runs 20, done 5, steps 220, tool calls 220, prompt tokens 572605, completion tokens 37306 と表示され、上にあるすべてのグループを含む。さらにもう一つのアサーションが記録を検査する。どの実行も1ステップにつきツール呼び出しを1回行っているため、ツール呼び出し数とステップ数は同じ数になる。

ステップ上限で終了した実行のうち、完了したものはない。件数は 0 of 7 と表示される。ステップ上限で終了した実行は finish でも引き継ぎでも終わらないため、完了の規則から、ファイルの内容にかかわらずゼロになる。ask_user グループで唯一完了とされた T-18 は、パスの一致によってその件数が得られている(第10章)。このゼロは、ステップ上限で終了したどの実行がどれだけ完了に近づいていたかについては何も語らない。本章はこれをタスクに関する知見として読まない。

判断であり、測定ではない。ステップ上限の行が示すのは、トークンを使い切りながら完了しなかった実行のコストである。第5章のリクエストごとのプロンプト予算ではなく、実行の総トークン数に対するトークン予算があれば、これらの実行はもっと早く止まっていたはずである。その代償は、後のステップで完了したかもしれない実行を止めてしまう可能性である。この記録ではその可能性を示せない。ステップ上限で終了した各実行は上限で止まっており、それ以降のステップを書き込んでいないからである。コストを増大させるのはプロンプト数である。ループは各ステップで会話記録の全体を再び送信する。プロンプト数がすべてのステップで増加するステップ上限の実行を数えると、7 of 7 となる。ステップ予算はステップ数を数えるので、長い実行ではトークン数に比べてコストを表す度合いが小さい。トークン予算を設定する場合、ハーネスは実行を独自の終了理由と独自の回数で終えるべきである。そうすれば、予算による打ち切りとステップ上限による打ち切りを区別できる。

第12章では、エージェントと固定パイプラインをこれらと同じ単位で比較する。この単位が役に立つのは、すべての実行が同じ方法で報告する場合に限られる。

実践ルール: コストは、各実行のステップ数、ツール呼び出し数、トークン数として、終了のしかたごとにグループ化し、グループを並べて表示して報告する。金額は示さない。ステップ上限のグループは、完了せずに費やされたトークンとして読み、別の指標が裏づけるまではタスクに関する証拠として読まない。

独自のフィールド名を保ち、境界で対応付ける

レコードのトークンフィールドは prompt_tokens と completion_tokens であり、本書独自のものである。OpenTelemetry プロジェクトは、生成 AI システムのテレメトリに関する規約を公開している。その GenAI スパンのページは、セマンティック規約のリビジョン v1.37.0 において、同じ 2 つの数を gen_ai.usage.input_tokens と gen_ai.usage.output_tokens と名付けている(the semantic conventions, GenAI spans)。このリビジョンでは、ページの状態は "Development" とされているため、名前は変わる可能性がある。本書は OpenTelemetry を使用しない。トークン数の例は、この 2 つの名前を本書のフィールドと並べて、データとしてのみ示す。また、OpenTelemetry のツールがトレースをどのように読み取るかについて、この章は何も主張しない。

本書が独自の名前を保つのは、実用上の理由による。トレースを別のツールへエクスポートする読者に必要なのは 1 つの対応表であり、標準に依存する箇所はその表だけである。標準が変わっても、本書のフィールド名は変わらない。対応付けによって、数が変わることはない。プロンプトのトークン数と補完のトークン数は、どちらの名前でも同じ数であり、トレースのレコードは書かれたときのままである。

実践ルール: 自分のプロジェクトでは、トレースのフィールドに、数えるものを表す名前を付ける。標準の名前への対応付けは、境界で 1 つの表にまとめて行い、その表の横に標準のリビジョンを書いておく。標準のリビジョンが変わったときは、表を再確認する。

何がうまくいかなくなるか、どう気づくか

1 つ目の誤りは result フィールドにある。refused の呼び出しは実行されていないので、refused をツールのエラーと取り違える読者は、見るべき場所を誤る。記録を見れば気づける。result は refused であり、malformed は構文解析エラーを示し、ツールのフィールドにはツール名ではなく malformed と書かれ、ゲートの行は空である。このようなステップの指示文は error: で始まり、ツールの失敗のように読める。したがって、指示文ではなく result と malformed を読むこと。

2 つ目の誤りは、デバッグのために追加したタイムスタンプである。タイムスタンプは実行のたびに出力を変えるので、変更後の最初の実行で、例の出力と記録された出力との比較が失敗する。修正するには、タイムスタンプを削除してステップ番号を使う。ステップ番号は実行のたびに同じであり、行を順序づけるには十分である。

3 つ目の誤りは、最初の節にある空行である。空行を JSON パーサーに渡す読み取り処理は、そこで失敗する。しかもファイルに問題がないのに、ファイルが壊れているかのように見える。空文字列で構文解析が失敗したときに気づける。修正は、空の断片を意図して読み飛ばし、読み飛ばしを数えるルールにすることである。例もそのようにしている。

4 つ目の誤りは、トレースを制御手段として扱うことである。トレースはゲートとサンドボックスが下した判断を記録するだけである。トレース自体は何も決定せず、すでに実行された呼び出しを取り消すこともできない。子の例で保留された終了は、第 6 章で説明するゲートによって保留された。コマンドに対する制限は、第 7 章のサンドボックスによるものである。問題のあった実行の後でトレースを読めば、ハーネスが何を許可したかが分かる。分かるのはそれだけである。

5 つ目は、この章の限界である。この章が追跡するのは組み込みツールだけである。ここでは MCP サーバーを追跡しないので、MCP の呼び出しがトレースにどう現れるかについて、この章では何も主張しない。ツールそのものは第 9 章で扱う。

実践ルール: 判断のためにトレースを信頼する前に、その result フィールドと stop フィールドを読み、次に、出力された合計値を保存された総計と照合すること。総計と一致しないトレースは、書き出し側にバグがある。そのトレースが記録する実行は、まだエージェントについての知見ではない。

この章で決めたこと

  • 各実行は、ステップごとに1行の JSON を、ステップの順に、キーをソートし、空白を入れず、ASCII のみで書き出す。空行は書かない。
  • ID は呼び出し側から渡されるカウンタから作る。実行は run-0001、呼び出しは run-0001-c1 とする。時計やランダムな値はトレースに入らない。
  • トークン数は、記録が保存していた値を用いる。実際のトークン数の確認は行わない。この点が問題になる箇所では、本章でその旨を述べている。
  • 子の記録は、自身の実行 ID と parent フィールドを持つ。親のコストに子の数が含まれるのは、レポートがそう示す場合に限る。
  • コストは、ステップ数、ツール呼び出し数、トークン数で表し、各実行の終わり方ごとにまとめる。本書は金額を示さない。
  • 本書のフィールド名は本書独自のものである。OpenTelemetry の名前はデータとして掲載するだけで、使用はしない。

トレースに要するコストはステップごとに1行である。その見返りとして、停止理由では答えられない問いに答えられる。どのステップが誤ったのか、ハーネスが何を拒否したのか、各ステップが何トークンを要したのか、という問いである。停止理由、スコア、コストは、数え上げの元になった行と同じ程度にしか検証できない。行を残し、ID を残し、数は記録が書いたとおりに残すこと。

実践ルール: 報告するすべての実行について、ステップごとに1行を、その ID と保存されたカウントとともに残すこと。それらの行までたどれない数値は報告しない。

この版における本章

第2026.11.2版2026年11月20日時点で例が通過この章の4 例件のうち4件が合格

英語版の書籍(版2026.11.2)から翻訳した。

この節を引用する

形式

いずれの形式も、本訳書が従う英語版の書籍を出典として示す。

いずれの形式もこの版を明示している。そのリンクは現行版を開き、節の見出しには本文が最後に変更された日付が示される。アクセス日と取得日は、これを開いた日である。

このページの内容

全12章中の第11章: 各実行をトレースし、そのコストを数える

  1. 1イベント1行
  2. 時計を使わないID
  3. 数としてのトークン
  4. 子の記録は親の呼び出しの下に置かれる
  5. コストは金額ではなく回数で表す
  6. 独自のフィールド名を保ち、境界で対応付ける
  7. 何がうまくいかなくなるか、どう気づくか
  8. この章で決めたこと

ページの先頭に戻るすべての章