← Back to Guides

Companion to the book Harness Engineering for Production AI Systems · this part maps to Book Ch 13

GuideFor: AI Engineers, ML Engineers, Platform Engineers, AI Systems Architects

AI Agent Spend Limits Pay for the Call That Crosses Them

A budget checked against what the run has already spent fires one unit late. Reserve the declared worst case of the next call, refund or fan-out before it runs, and settle the real cost after.

#harness-engineering#llm-cost#budget-enforcement#langgraph#llm-agents#production-ai-systems

At 01:40 the billing agent was draining the overnight queue. One customer wrote that they had been charged twice for months and pasted 31 invoice numbers. For each invoice the agent opened one lookup and asked the model about it, and it found 11 duplicates. Each refund was 40.00, under the 50.00 automatic band from Part 9, and each passed every gate this series has built. When the morning shift came in, 440.00 was gone. A tool-call ceiling with a limit of 12 was in place. It read a counter that said 0 before the refunds. All 31 lookups and their 31 model calls had run inside branches, and no branch could write that counter.

I constructed this scenario from the billing agent this series has followed since Part 1. Unlike the scenario, the vendor caps below are real. Anthropic's Agent SDK says of its own spend cap that "Spend can therefore pass the cap by up to the cost of that one response, plus anything that subagents still running at that moment spend before they stop." In amicus issue #158, a run with max_budget_usd: 1.00 ended at 3.36, "an overshoot of 3.4x." Amounts in this part are US dollars.

My claim is that a spend limit is a bound only if it can refuse the unit that would cross it, and that everything it needs to refuse in time can be declared, enforced by whatever spends it, and checked before the first run. To refuse in time, the limit reserves the next unit's worst case before the unit runs and settles the real cost afterwards. Each worst case comes from a declared number. For a model call, that is the call's token maximums priced by a dated price table. A refund's worst case is the largest amount the approval gate lets through without a person. A fan-out's is the width the node will actually open, capped by its declared maximum, times what one branch can cost. None of it comes from the proposal or from last month's spend.

Reserving before a call is published work, and this blog's July post already reserved fan-out width at the dispatch site; I credit both below. My contribution is what declaring buys. Once every worst case is a number in a file, every limit is arithmetic, and the loader can prove before the first run that the cost limit pays for one proposal that climbs the whole repair ladder, and that each fan-out fits inside an empty run. On this part's numbers, that proof rejects a 0.60 cost limit, because one worst-case proposal costs 1.152, and a 24-branch fan-out, because it needs 25 calls in a run that allows 20. Sizing a limit the usual way, from typical spend plus a margin, fails that proof.

Why AI agent spend limits overshoot by one call

Common advice on this has two halves. Size the limit from what typical runs cost, plus a margin. Enforce it by checking the run's spend so far before each call, and leave some headroom for the call that crosses. Archestra puts the first half plainly: "Sizing rule of thumb: roughly 3-5x the cost of a typical successful run." Its own sample error object shows the second half at work, a cap of 2.0 reporting "used_usd": 2.04. Vendors supply the second half in their own documentation.

  • Claude Agent SDK, max_budget_usd: it "compares spend with the max_budget_usd / maxBudgetUsd cap after model responses arrive", and "Leave headroom for this when you set the cap."
  • Claude Managed Agents, session budgets: "The cap is enforced between model requests, not mid-request." And: "Model spend past the cap is at most the cost of one model request for each thread."
  • OpenAI organization and project hard limits: "Enforcement is not instantaneous, so recorded spend can slightly exceed the configured amount."

All three are honest about what they do, and all three check spend that has already happened. Two of them put a size on the headroom: the Agent SDK sizes it as one response plus whatever running subagents spend, and Managed Agents as one request per thread. Both sizes grow with concurrency, which is why no fixed margin works.

d2
direction: right
classes: {
  check: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  spend: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  over: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
c1: "Check\n0.95 spent of 1.00\nunder: pass" {class: check}
call: "Next call runs\ncosts up to 2.40" {class: spend}
total: "Total is now 3.35\nthe cap is 1.00" {class: over}
c2: "Check\nover: refuse" {class: check}
c1 -> call -> total -> c2

Before the call, the check reads a total that is under the cap, so it lets the call through. Its refusal comes at the next check, after the money is spent. The overshoot can be as large as the whole call that crossed, here 2.35 of a 2.40 call, and the check never knew that size.

Published measurements match the documentation. Real money went out in the amicus run above. In a blog post from April 2026, LinuxJedi set a cap of 0.01 and got back "total_cost_usd": 0.08440724999999999 on one turn. In claude-code issue #100111, titled "--max-budget-usd is checked after each call returns, so a $1 cap stops at $1.38", a 10.00 cap stopped at 12.06. That issue was filed by an AI agent and measured against a local stand-in API, so it tests the mechanism and lost no money.

The Receipt Ceiling: a limit checked against spend already incurred

My book names this failure The Receipt Ceiling: "a limit checked against spend already incurred." Because it reads only what is gone, it fires after the overrun it was set to prevent. Its overrun is as large as the biggest unit the limit admits: one call at its worst, one refund, or every branch of a fan-out. To fix it, hold the next unit's worst case before the unit runs, then settle the true cost from what the unit reports.

That name says what the check reads: a receipt for money already gone. Two sources use the word "receipt" for the opposite thing. In the Token Budgets paper (arXiv 2606.04056), a ReservationReceipt is the token for a reservation, and SpendGuard uses receipts as signed audit records. In this article a receipt is only ever a record of spend that has already happened.

d2
direction: right
classes: {
  unit: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  size: {style: {fill: "#FFA07A"; stroke: "#C96F4A"; font-color: "#2C2C2A"}}
}
grid: {
  grid-rows: 4
  grid-columns: 2
  grid-gap: 24
  label: ""
  style: {fill: "#FFFFFF"; stroke: "#FFFFFF"}
  u1: "A model call" {class: unit}
  s1: "Overshoot: one call at\nfull context and max output" {class: size}
  u2: "A refund" {class: unit}
  s2: "Overshoot: the largest refund\nthe gate passes on its own" {class: size}
  u3: "A fan-out" {class: unit}
  s3: "Overshoot: width x\nwhat one branch costs" {class: size}
  u4: "Threads sharing a cap" {class: unit}
  s4: "Overshoot: one request\nper thread in flight" {class: size}
}

In every row, the overshoot is set by something the check never reads: the size of the next unit. Two of those sizes are chosen at run time. By deciding how many invoices to paste, the customer chose 31, and whoever scheduled the work chose how many threads were in flight.

I did not invent the idea that a check fires too late. Tian Pan wrote in June that "The cap fires between model calls. It does not fire between tool calls." A concurrent form is named in the Token Budgets paper, and I come back to it below.

For a count of calls, a check before the call is already exact. Part 8's RunBudget checks requests sent against requests allowed before it sends, and LangChain's ModelCallLimitMiddleware checks run_count >= self.run_limit before the model runs. When every unit is the same size, 1, "would one more cross the limit" and "has the count reached the limit" are the same question. Where units vary in size, as money, tokens and refund amounts do, the Receipt Ceiling appears. It also appears where units arrive in batches, as they do in a fan-out, unless the check counts the whole batch. LangChain's ToolCallLimitMiddleware does exactly that for tool calls: it checks whether one more call would pass the limit for each call in a parallel batch, before any of them runs.

Wrong way: a spend limit checked against spend so far pays the refund that crosses it

Part 3 of this series set up the choice this section finishes. It ran three refunds of 1,500 against a daily limit of 2,000. A blind bound that read only the ledger total let 3,000 out, because it checked before each refund and was under the limit both times. Its next question was why we should not check refunded_today + amount instead, and its answer was that this check reads the proposal, so it is a gate. A gate trusts that the amount the model wrote is the amount that will move. Part 3 kept both checks, the gate for honest amounts and the blind bound for everything else, and it ended with "A later part of this series measures that overshoot." This is that part.

Four checks run on three streams of refunds in the demo below. In queue-drain mode, the per-run limit for issue_refund is 150.00, and the gate's automatic band is 50.00. Each refund carries three amounts: the one the proposal states, the one the ledger line holds, and the one that actually moves at the payment processor. After Part 10 narrowed the signature to issue_refund(line_id), the amount requested always comes from the ledger, and the proposal's stated figure survives only in the model's rationale. That figure is what projection reads. The careful check resolves the line from the ledger instead, which is what a well-built projection does after Part 10.

python
# receipt_vs_reservation.pyfrom decimal import DecimalMAX_TOTAL = Decimal("150.00")   # issue_refund, queue-drain, per runAUTO_BAND = Decimal("50.00")    # the largest ledger amount the gate passes on its ownclass BoundExceeded(Exception):    passdef receipt(moved: Decimal, proposed: Decimal, line: Decimal) -> None:    """Check what has already left."""    if moved >= MAX_TOTAL:        raise BoundExceeded(f"{moved} moved, limit {MAX_TOTAL}")def projection(moved: Decimal, proposed: Decimal, line: Decimal) -> None:    """Check what has left plus what the model says the next refund is."""    if moved + proposed > MAX_TOTAL:        raise BoundExceeded(f"{moved} + {proposed} proposed > {MAX_TOTAL}")def careful(moved: Decimal, proposed: Decimal, line: Decimal) -> None:    """Check what has left plus the ledger line the proposal names."""    if moved + line > MAX_TOTAL:        raise BoundExceeded(f"{moved} + {line} on the line > {MAX_TOTAL}")def reservation(moved: Decimal, proposed: Decimal, line: Decimal) -> None:    """Check what has left plus the most the next refund can move. Reads neither."""    if moved + AUTO_BAND > MAX_TOTAL:        raise BoundExceeded(f"{moved} + {AUTO_BAND} reserved > {MAX_TOTAL}")def drain(refunds: list[tuple[str, str, str]], check) -> str:    """refunds: (amount the proposal states, the ledger line, what actually moves)."""    moved = Decimal("0")    paid = 0    for proposed, line, actual in refunds:        try:            check(moved, Decimal(proposed), Decimal(line))        except BoundExceeded as exc:            return f"paid {paid}, {moved} out; refused: {exc}"        moved += Decimal(actual)        paid += 1    return f"paid {paid}, {moved} out"if __name__ == "__main__":    streams = {        "five honest 40.00": [("40.00", "40.00", "40.00")] * 5,        "five misread lines": [("10.00", "45.00", "45.00")] * 5,   # model wrote 10.00        "five 40.00 lines, 55.00 moves": [("40.00", "40.00", "55.00")] * 5,  # a fee    }    for name, refunds in streams.items():        print(f"=== {name}, limit {MAX_TOTAL}")        for check in (receipt, projection, careful, reservation):            print(f"  {check.__name__:<12} {drain(refunds, check)}")

Run with Python 3.12, standard library only:

text
=== five honest 40.00, limit 150.00  receipt      paid 4, 160.00 out; refused: 160.00 moved, limit 150.00  projection   paid 3, 120.00 out; refused: 120.00 + 40.00 proposed > 150.00  careful      paid 3, 120.00 out; refused: 120.00 + 40.00 on the line > 150.00  reservation  paid 3, 120.00 out; refused: 120.00 + 50.00 reserved > 150.00=== five misread lines, limit 150.00  receipt      paid 4, 180.00 out; refused: 180.00 moved, limit 150.00  projection   paid 4, 180.00 out; refused: 180.00 + 10.00 proposed > 150.00  careful      paid 3, 135.00 out; refused: 135.00 + 45.00 on the line > 150.00  reservation  paid 3, 135.00 out; refused: 135.00 + 50.00 reserved > 150.00=== five 40.00 lines, 55.00 moves, limit 150.00  receipt      paid 3, 165.00 out; refused: 165.00 moved, limit 150.00  projection   paid 3, 165.00 out; refused: 165.00 + 40.00 proposed > 150.00  careful      paid 3, 165.00 out; refused: 165.00 + 40.00 on the line > 150.00  reservation  paid 2, 110.00 out; refused: 110.00 + 50.00 reserved > 150.00

On honest amounts, the receipt pays a fourth refund and ends at 160.00: it read 120.00, saw that it was under 150.00, and paid the refund that crossed. Every check that looks ahead stops at three. On the second stream, the model wrote 10.00 in each proposal and named lines of 45.00. Each refund passed the gate, which resolves the amount from the ledger, and 45.00 is under 50.00. Trusting the 10.00, the projection paid four refunds and ended at 180.00. Reading the line, careful stopped at three, and so did the reservation, which read neither amount.

So far careful looks as good as the reservation, and it is more generous: at 120.00 out it would let a 5.00 refund through, where the reservation refuses. It is still a gate by Part 3's test, which asks whether a decision depends on this proposal, because its answer depends on which line the proposal picked. It also repeats the gate's own resolution step, so it fails where the gate fails. Part 3 named that place: an amount whose real movement differs from the one the check read, such as a second currency. A processor fee charged on the refund is another case.

The third stream is that case. Each line says 40.00 and 55.00 moves. Every check except the reservation lets three refunds out and ends at 165.00. Because it reserves the band rather than the line, the reservation stops at two and 110.00. Each 55.00 refund still moved 5.00 more than the reservation held, so a run sitting just under the limit could overshoot by that difference. The next reservation reads the real total, so the error is capped at one refund's excess over the band. Part 3 recommended a per-transaction limit on the payment account as well, and where the account has one at or below the band, or where the reservation reserves that limit instead of the band, it closes the gap. The band bounds the ledger amount, and only the processor's limit bounds what moves. A declared number is a worst case only where something enforces it: the API's max_tokens for a model call's output, the gate's band for a refund's ledger amount, and the account's own limit for what the processor moves. Keep careful as a gate for the exact answer on honest proposals, as Part 3 kept its gate, and put the reservation beside it as the bound.

d2
direction: right
classes: {
  src: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  bad: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  late: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  good: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
ledger: "Ledger total\nwhat has left" {class: src}
proposal: "Proposal amount\nwhat the model wrote" {class: bad}
band: "Gate band\nlargest ledger amount it passes" {class: src}
receipt: "Receipt: blind, late\npays the unit that crosses" {class: late}
projection: "Projection: early, a gate\ntrusts the amount" {class: bad}
reservation: "Reservation: blind and early\nbounds the ledger amount" {class: good}
ledger -> receipt
ledger -> projection
proposal -> projection
ledger -> reservation
band -> reservation

This finishes Part 3's split, which had two choices: a projected gate that is early but trusts the amount, and a blind bound that ignores the amount but fires late. What the reservation reads is the ledger and a number from the gate's own policy file. Part 3's question 3 asks whether a component's decision depends on this proposal. For the reservation the answer is no, so it is a bound, and unlike the blind bound it fires before the money leaves. It is conservative on purpose. With 120.00 out, it refuses a refund that might have been 5.00. For money leaving the company overnight, I prefer that error, and the refused refund goes to a person in the morning.

In queue-drain mode the numbers interact, and the declaration should show it. Three refunds of at most 50.00 is 150.00, so in this mode the total and the count of 3 agree. Both are in the book's per-run limit, and in the full harness the count is the check that fires on the honest stream. If a later edit raises the band, the total starts to bind before the count does, and the reservation follows the band because it reads the band. A per-run total still bounds one run, not the night, and an aggregate spending limit for AI agents across runs is Part 14's job.

Inside a fan-out, every branch reads the same budget snapshot

Now back to the opening, where the tool-call ceiling read 0 because the branches could not write the run's counter. An obvious fix is to move the check into each branch, so every lookup checks the budget before its model call. LangGraph's Send gives each branch its own input: a copy of the counter taken when the fan-out ran, and every branch gets the same copy. This demo counts model calls rather than tool calls, so the proposal is call 1 before the fan-out.

python
import operatorfrom typing import Annotated, TypedDictfrom langgraph.graph import END, START, StateGraphfrom langgraph.types import SendCALL_LIMIT = 20   # model calls per run, queue-drainMAX_WIDTH = 16    # the most branches lookup may openBRANCH_CALLS = 1  # each judge branch makes one model callclass Run(TypedDict, total=False):    invoices: list[str]    model_calls: int                            # the run's counter    judged: Annotated[list[str], operator.add]  # branches append here    refused: strclass Branch(TypedDict):    invoice: str    model_calls: int                            # the counter as the branch saw itdef judge_checked(b: Branch) -> dict:    if b["model_calls"] + BRANCH_CALLS > CALL_LIMIT:    # reads a snapshot, not siblings        raise RuntimeError(f"call ceiling: {b['model_calls']} spent")    return {"judged": [b["invoice"]]}def judge(b: Branch) -> dict:                           # paid for at lookup    return {"judged": [b["invoice"]]}def settle(state: Run) -> dict:    return {"model_calls": state["model_calls"] + BRANCH_CALLS * len(state["judged"])}def in_branch(state: Run) -> list[Send]:    return [Send("judge", {"invoice": i, "model_calls": state["model_calls"]})            for i in state["invoices"]]def lookup(state: Run) -> dict:    """Reserve for every branch before any branch exists."""    width = len(state["invoices"])    if width > MAX_WIDTH:        return {"refused": f"lookup would open {width} branches; "                           f"its limit is {MAX_WIDTH}"}    need = state["model_calls"] + BRANCH_CALLS * width    if need > CALL_LIMIT:        return {"refused": f"{need} model calls reserved; the run allows {CALL_LIMIT}"}    return {"model_calls": need}               # reserved for every branch, up frontdef reserved(state: Run) -> list[Send] | str:    if state.get("refused"):        return "escalate"    return [Send("judge", {"invoice": i, "model_calls": state["model_calls"]})            for i in state["invoices"]]def build(reserve: bool):    g = StateGraph(Run)    g.add_node("lookup", lookup if reserve else (lambda s: {}))    g.add_node("judge", judge if reserve else judge_checked)    # a count meter: what lookup reserved is what the branches spend, so nothing settles    g.add_node("settle", (lambda s: {}) if reserve else settle)    g.add_node("escalate", lambda s: {})    g.add_edge(START, "lookup")    g.add_conditional_edges("lookup", reserved if reserve else in_branch,                            ["judge", "escalate"])    g.add_edge("judge", "settle")    g.add_edge("settle", END)    g.add_edge("escalate", END)    return g.compile()for n, spent in ((31, 1), (12, 1), (9, 12)):    # 12: the proposal used its ladder    ticket = {"invoices": [f"inv_{9000 + k}" for k in range(n)], "model_calls": spent}    for reserve in (False, True):        out = build(reserve).invoke(ticket)        where = "reserve at lookup" if reserve else "check in branch  "        print(f"{n} invoices, {where}: judged {len(out.get('judged', []))}, "              f"model_calls {out['model_calls']} of {CALL_LIMIT}")        if out.get("refused"):            print(f"    refused: {out['refused']}")

Run on langgraph 1.2.22, the current release, and on 1.2.12, with identical output:

text
31 invoices, check in branch  : judged 31, model_calls 32 of 2031 invoices, reserve at lookup: judged 0, model_calls 1 of 20    refused: lookup would open 31 branches; its limit is 1612 invoices, check in branch  : judged 12, model_calls 13 of 2012 invoices, reserve at lookup: judged 12, model_calls 13 of 209 invoices, check in branch  : judged 9, model_calls 21 of 209 invoices, reserve at lookup: judged 0, model_calls 12 of 20    refused: 21 model calls reserved; the run allows 20

All 31 branches read model_calls as 1, and 1 + 1 is under 20 in every one of them, so the run made 32 model calls against a limit of 20. Each branch check does include its own next call, so on its own it looks like a projection. For the fan-out as a whole, though, it reads a receipt of the run's spend, taken before any sibling ran. Its overshoot is the width times one branch, because every branch checks against a total that leaves out all of its siblings. With reservation, the 31-invoice ticket is refused at lookup on width, before any branch exists, and that refusal is the July post's width bound.

The third ticket is the new case. Its proposal used all 12 calls of its repair ladder, and it lists 9 invoices, well inside the width limit. Every branch reads 12, finds 12 + 1 under 20, and the run ends at 21 calls. At lookup, the reservation adds the whole width to the 12 before any branch opens, gets 21, and refuses.

d2
direction: down
classes: {
  node: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  branch: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  over: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
}
lookup: "lookup\nmodel_calls = 1\nopens 31 branches" {class: node}
step: "One superstep" {
  style: {fill: "#F4F1FF"; stroke: "#5A4BC4"; font-color: "#2C2C2A"}
  b1: "branch 1\nreads 1\n1 + 1 <= 20: pass" {class: branch}
  b2: "branch 2\nreads 1\n1 + 1 <= 20: pass" {class: branch}
  b31: "branch 31\nreads 1\n1 + 1 <= 20: pass" {class: branch}
}
settle: "settle\nmodel_calls = 32\nlimit was 20" {class: over}
lookup -> step.b1
lookup -> step.b2
lookup -> step.b31
step -> settle

None of the 31 checks is wrong on its own input. That input is a snapshot taken before any sibling spent anything, and inside graph state, the only place the whole width is visible is the node that opens the branches.

This blog published the other half of this picture in July. LangGraph's recursion_limit Bounds Depth, Not Width measured a thousand workers under a recursion limit of 4. It named the pattern a Width-Blind Bound and put the bound at the dispatch site, with a claim_width ledger that reserves width units for the thread, in one compare-and-swap, before any worker starts. My book calls the same thing the Width Gap. I will not argue it again here. Reserving per branch is not new either: the Token Budgets paper's shared pool has each delegated call reserve "its worst-case cost pre-flight", so the cap holds at any width. My addition is pricing the width from a declared shape before the fan-out opens. The reservation multiplies the width by the branch's declared call shape and holds the product against the run's limits, the same limits every other unit reserves against. The demo reserves against the call limit only. Its third ticket fits its width budget and is still refused for the 21 model calls it would make. The book's harness holds the same product against the cost limit too. Per-branch reservation against a shared pool would judge eight of the nine invoices and escalate one. I prefer refusing the whole ticket, because a person in the morning can work a ticket that was refused whole, while a ticket judged in part has to be untangled first.

Branches still need to record what they spent, and a plain field will not take it. Two branches that each return the run's budget in the same step raise InvalidUpdateError: At key 'budget': Can receive only one value per step. ..., which goes on to suggest an Annotated key. In the book's harness, RunState has a journal of Spend records, typed Annotated[tuple[Spend, ...], operator.add], so branches append to it, and a settle node after the branches computes the budget again from the whole journal. My other book, Building Real-World Agentic AI Systems with LangGraph, covers the framework side in Chapter 17, "Subgraphs, Parallelism, and Map-Reduce": it builds the Send fan-out with a reducer for the fan-in, and handles a branch that dies partway through.

Right way: reserve an LLM call's declared worst-case cost before it runs

At the center of the book's harness is one function, reserve(config, policy, run, worst). It reads the run's totals and a worst-case Spend, and it raises before the unit runs. For a tool that moves money, it reads the journal for earlier calls to the same tool in this run. Then it applies a count and a total:

python
# harness/ceilings.py, tag ch13-cost-depth-width (excerpt)    earlier = [s for s in run.spend if s.tool == worst.tool]    if len(earlier) + 1 > limit.max_count:        raise BoundExceeded(            f"{worst.tool}-count",            f"{len(earlier)} already this run, limit {limit.max_count} in "            f"{run.mode.value}",        )    ceiling_amount = worst_amount(policy, worst.tool, run.mode.value)    if ceiling_amount is None:        return    moved = sum((s.amount for s in earlier), Decimal("0"))    if moved + ceiling_amount > limit.max_total:        raise BoundExceeded(            f"{worst.tool}-total",            f"{moved} moved and up to {ceiling_amount} more would pass "            f"{limit.max_total} in {run.mode.value}",        )

worst_amount is the function Part 9 wrote to read the gate policy. Where a mode has a review band it returns the top of that band, and otherwise it returns the automatic band. The early return for a money tool with no band is safe only because the loader's tool check refuses to start with a money limit on a tool the gate does not band. Because the gate already declares the largest single refund, the budget file never declares it. Writing it twice would be Part 10's Split Declaration: two numbers for one limit, free to drift apart. With the count, the harness closes the gap that Parts 9 to 12 each left open for this part: a gate judges one proposal and cannot see the other refunds in the same run. Part 12 had a related reason to want it. Its effect log refuses a second identical refund in one run as a replay, and the count makes the general rule explicit: past the count, a further refund in the same run is never automatic.

A model call works the same way with a different source. worst_call(node) reads the node's declared call shape, which names a model and the maximum input and output tokens. It prices that shape with the dated price table and raises if the node declares no shape. For the propose node, the shape is the 32,000-token window from Part 5, less 4,000 tokens kept for output. At Sonnet 5's 2.00 and 10.00 per million tokens, that comes to 0.056 for input and 0.040 for output, so one propose call can cost at most 0.096. That maximum assumes the call writes no prompt cache. Sonnet 5 charges 2.50 per million tokens for a five-minute cache write and 4.00 for a one-hour write, so a node that writes its 28,000-token prompt to a one-hour cache can spend 0.112 on input alone, and its shape has to declare that rate. The book's propose node writes no cache. If it wrote a one-hour cache, the same check would price the ladder at 1.824 and reject the shipped 1.50 as well. The input maximum also has to be enforced with the provider's own token count, or carry a margin for whatever approximation the assembler counts with. A fan-out multiplies the branch's worst case by the width and reserves the product in one call to reserve, before it opens any branch. Once a node has passed the reservation, it does its work and then records what the work really cost, from the provider's usage report on the response, priced with the same table. Inside the graph, ceilings is the RunCeilings component, which holds the config and the gate policy, so a node passes only the state and its worst case:

python
# harness/graph/ceilings.py, tag ch13-cost-depth-width (excerpt)    def node(state: Any) -> dict[str, Any]:        try:            ceilings.reserve(state, replace(worst, depth=worst.depth + 1))        except BoundExceeded as exc:            return stopped(state, exc)        update, actual = work(state)        actual = replace(actual, depth=actual.depth + 1)        return {**update, "spend": (actual,), "budget": state.budget.after(actual)}

Running the book's example at the chapter's tag gives this output, identical on langgraph 1.2.12 and 1.2.22. First comes the opening ticket, then a ticket of twelve invoices with five charged twice:

text
=== the same ticket with the budget config  lookup-width: exceeded: lookup would open 31 branches; its limit is 16model calls 1, refunds 0, supersteps 3=== twelve invoices listed, five charged twice  issue_refund-count: exceeded: 3 already this run, limit 3 in queue-drainrefunded 3 of 5: 120.00budget: model_calls 13  tool_calls 15  tokens 13600/580  cost 0.021depth 9, supersteps 9, recursion_limit 19; width 12budget == fold(journal): True

After one model call, the proposal, the 31-invoice ticket stops. In the book's example it escalates with all 31 invoice numbers still on its state, for a person to work in the morning. With twelve invoices, three refunds go out, and the count refuses the fourth before it is paid. A person gets the remaining two. Depth in the harness and LangGraph's superstep count agree at 9, and the budget equals a fresh total computed from the journal.

d2
direction: right
classes: {
  decl: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  step: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  stop: {style: {fill: "#FFA07A"; stroke: "#C96F4A"; font-color: "#2C2C2A"}}
  done: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
}
worst: "Worst case\nfrom declared numbers" {class: decl}
reserve: "reserve()\ntotals + worst <= limit?" {class: step}
work: "Do the work\none call, one refund,\nor open the branches" {class: step}
settle: "Settle\nreported usage\ninto the journal" {class: done}
escalate: "Refuse before spending\nescalate with the reason" {class: stop}
worst -> reserve
reserve -> work: "fits"
reserve -> escalate: "does not fit"
work -> settle

Reservations use the declared worst case, and the journal records the actual cost. Every later reservation reads the journal, so an overestimate at one step never builds up into refusals at the next: the next step reserves against what the run really spent.

Depth uses the same reservation. Each node counts itself as one step of depth when it reserves. That way the depth ceiling refuses a step before the step runs, and LangGraph's recursion_limit becomes a backstop computed from the depth ceiling. To the ceiling, the book adds 3: one step for the refused node, which still runs, one for the walk to the escalation node, and one because LangGraph's loop ticks once more than the steps a node reports. In the July post's words, "a graph whose deepest node reports step 3 needs recursion_limit=4". On langgraph 1.2.11 the book measured that last one, where eight nodes in a row fail at a limit of 8 and pass at 9, and the chapter's example gives the same result on 1.2.22. A first draft that added 1 crashed on the way to escalation.

Declared, not estimated: limits you can check before the first run

Reserving before a call is no longer unusual, and I want to be exact about what is new here. LiteLLM's proxy reserves by default: "Budget reservation is enabled by default." Its documented first step reads "LiteLLM estimates the request's maximum cost from the request body and the model's pricing." Then it holds that amount and replaces it with the actual cost when the response is priced. Reservation of this kind prevents a concurrent failure that the Token Budgets paper (Khan, 2026) measured with its own locked reservation.

Three child agents checked one shared budget with no lock, and "all three children pass can_admit on the same pre-spend state and proceed, spending 3×23=69 uc against the 60 uc cap ...". That happened in 30 of 30 trials. With a locked reservation made before each call, it happened in 0 of 30. Khan also says plainly: "The runtime mechanism itself (pre-call reservation with conservative estimation) is not novel." Agent Contracts (Ye and Tan, 2026) goes further, with conservation laws that keep the budgets delegated to sub-agents within the parent's. That checks one budget against another along the delegation tree. Card payments use it too: Stripe lets you "place a hold on an eligible payment method to reserve funds that you can capture later."

So I claim nothing about the mechanism; my claim is about the input. LiteLLM's estimate already uses declared numbers for output: "When max_tokens or max_completion_tokens is present, LiteLLM uses that value in the estimate." Without them, it uses the model's configured limits. Its input side is priced from the request body. LiteLLM has no declared source at all for units that are not tokens, such as a refund or the width of a fan-out. For a model call, the harness builds the request itself, so pricing input from it is honest and usually tighter than a declared maximum. For a tool that moves money, the request is the model's proposal, and an estimate from the proposal is the projection that paid four refunds above. Every per-unit price in the harness therefore comes from a declared number. The only thing read from the unit is a size the harness enforces itself: the list a fan-out is about to open, capped by the declared max_width.

d2
direction: right
classes: {
  decl: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  res: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  no: {style: {fill: "#FFD93D"; stroke: "#C9A400"; font-color: "#2C2C2A"}}
  cut: {style: {stroke-dash: 4; stroke: "#B03A2E"; font-color: "#B03A2E"}}
}
callshape: "Call shape x dated price table\npropose: 0.096 per call" {class: decl}
band: "Gate band, via worst_amount\nissue_refund: 50.00" {class: decl}
fanout: "width, at most max_width 16\nx branch shape 0.003" {class: decl}
reserve: "Reservation\nper-unit worst case\nknown before the run starts" {class: res}
proposal: "The proposal's amount\nnever read" {class: no}
history: "Last month's spend\nnever read" {class: no}
callshape -> reserve
band -> reserve
fanout -> reserve
proposal -> reserve: "x" {class: cut}
history -> reserve: "x" {class: cut}

A second reason matters even where an estimate would be safe, and it is the reason I would use declared shapes for model calls too. A declared number exists before the first run, so the loader can multiply declared numbers together and check them against each other. An estimate made from the request exists only at 01:40, inside the run that needed it. The next section runs two checks that only declared numbers allow, and the book reports that both caught mistakes in its own first draft.

Kubernetes ResourceQuota takes the same position. In a namespace with a CPU or memory quota, every new Pod must declare requests or limits for that resource, or the control plane may refuse it. At its own scale, the harness does the same: worst_call raises when a node makes a model call without declaring a shape. The quota checks each Pod's declared numbers against the namespace at admission. The harness goes one step further. It checks the declared limits against each other at load, before any run. The book runs four such checks: the cost limit against the repair ladder times the call shape, each fan-out's width against the run's call limit, two files that both declare a call budget against each other, and every tool limit against the registry and the gate's band. The first two caught mistakes in the book's own first draft. It also checks the fleet hold's expiry against the run's wall-clock limit.

The closest prior art I found is Qwen Code's batch planner, which agent-errata's study S005 reports "refuses to submit a batch whose worst case exceeds maxCostUsd". That is a declared worst case checked before a batch. The habit of checking one limit against another is old: a request deadline has to cover its retries times the per-try timeout. What I did not find in agent budget tooling is checking spend limits against the declared shape of the work they bound, before any batch exists: the repair ladder times retries times a priced call shape against the cost limit, and fan-out width times branch calls against the run's call limit.

This blog's own earlier cost posts sit on the estimate side of this line, and they are right for what they cover. Why Your Agentic RAG System Costs 10x More Than It Should has both kinds of check: a receipt, tokens_used >= budget_tokens, and a pre-call check of tokens_used + tokens_this_call, which projects the input tokens and leaves output unpriced. Cost Governance and Budget Allocation Across Agent Types debits a caller-supplied estimated_cost_usd under a lock before the call. That is already a reservation, made from an estimate. Its code never settles the estimate to the actual cost, though its checklist asks for reconciliation against provider-reported usage. Neither prices a refund, and neither has a number the loader could check against the work before a run.

Why LLM cost caps sized from typical spend refuse the runs that need them

An ordinary twelve-invoice run, like the one above, cost 0.021, and the common advice multiplies that by a margin. Anthropic gives the observed-spend version of this advice for task budgets, "Start with the p99 of your per-task token spend", where p99 means the 99th percentile. That is good advice for a task budget, because the same page says "Task budgets are a soft hint, not a hard cap." A hint should be sized to what runs usually need. A hard limit has a different job: it must pay for the worst case of each unit of legitimate work, and the combinations it cannot pay for must be computed and written down rather than discovered.

For this agent, the worst legitimate run is the repair ladder. A proposal is its first call plus the three repair calls that Part 7's ladder can make: two re-asks and one narrowing. Part 8's retry policy may try each of those four calls three times, so the proposal can make twelve calls. All of these numbers are declared, so the loader can do the multiplication:

python
from decimal import Decimal# Declared artifacts. Prices per million tokens, verified 2026-11-15 against# https://platform.claude.com/docs/en/about-claude/pricingPRICES = {"claude-sonnet-5": ("2.00", "10.00"), "claude-haiku-4-5": ("1.00", "5.00")}CALL_SHAPES = {                     # node: (model, max tokens in, max tokens out)    "propose": ("claude-sonnet-5", 28_000, 4_000),    "judge": ("claude-haiku-4-5", 2_000, 200),}LADDER_CALLS = (1 + 3) * 3          # first call + 3 repair calls, each tried 3 timesdef worst_call(node: str) -> Decimal:    if node not in CALL_SHAPES:        raise ValueError(f"{node} makes a model call and declares no call shape")    model, tokens_in, tokens_out = CALL_SHAPES[node]    p_in, p_out = (Decimal(p) for p in PRICES[model])    return (tokens_in * p_in + tokens_out * p_out) / 1_000_000def unaffordable(cost_limit: Decimal) -> str | None:    need = LADDER_CALLS * worst_call("propose")    if need > cost_limit:        return f"one worst-case proposal costs {need} and the run may spend {cost_limit}"    return Nonedef refused_at_worst(cost_limit: Decimal) -> int | None:    """Which call of a ladder is refused if every attempt settles at its worst case."""    for n in range(1, LADDER_CALLS + 1):        if n * worst_call("propose") > cost_limit:            return n    return Nonedef unreachable(max_width: int, call_limit: int, branch_calls: int = 1) -> str | None:    need = 1 + max_width * branch_calls     # the proposal, then the fan-out;                                            # the book's check counts branches only    if need > call_limit:        return f"lookup at its limit of {max_width} needs {need} calls of {call_limit}"    return Nonetypical = Decimal("0.021")                          # an ordinary twelve-invoice runprint(f"worst propose call {worst_call('propose')}, "      f"worst judge call {worst_call('judge')}")limits = {"3x typical": typical * 3, "5x typical": typical * 5,          "0.60, about 29x": Decimal("0.60"), "shipped 1.50": Decimal("1.50")}for label, limit in limits.items():    verdict = unaffordable(limit) or "pays for one worst-case proposal"    print(f"  cost {label:<16} {verdict}")    if (n := refused_at_worst(limit)) is not None:        print(f"    climbing the ladder, call {n} of {LADDER_CALLS} is refused")for width in (24, 16):    print(f"  max_width {width}: {unreachable(width, call_limit=20) or 'reachable'}")print(f"  after a full ladder: {20 - LADDER_CALLS} calls left for the fan-out")
text
worst propose call 0.096, worst judge call 0.003  cost 3x typical       one worst-case proposal costs 1.152 and the run may spend 0.063    climbing the ladder, call 1 of 12 is refused  cost 5x typical       one worst-case proposal costs 1.152 and the run may spend 0.105    climbing the ladder, call 2 of 12 is refused  cost 0.60, about 29x  one worst-case proposal costs 1.152 and the run may spend 0.60    climbing the ladder, call 7 of 12 is refused  cost shipped 1.50     pays for one worst-case proposal  max_width 24: lookup at its limit of 24 needs 25 calls of 20  max_width 16: reachable  after a full ladder: 8 calls left for the fan-out

Applying the vendor rule of three to five times a typical run gives 0.063 to 0.105. A limit of 0.60 feels generous, at about 29 times the ordinary run. All three are below 1.152, the cost of one proposal that climbs the whole ladder. A run that needs the whole ladder is the run that is struggling, and each of these limits refuses it. The indented lines show where, for a ladder in which every attempt settles at its declared maximum. That is the struggling case, where each re-ask carries a growing context. Under that assumption the 0.60 limit refuses call 7 of 12, in the middle of the retries. At 0.60, ordinary attempts would all fit: the book's stand-in proposal reports 3,400 tokens in and 220 out, about 0.009 per call.

At three times typical, the reservation refuses even the first call of an ordinary run, because 0.063 is less than one worst-case propose call: that limit refuses every run. Even so, the run reaches a person, because the refusal escalates with its reason. What it loses is the rest of the ladder. The narrowed question that might have repaired the proposal never runs, and the person gets a budget refusal instead of the case Part 7's Deferral Rung would have handed over, with the rung each attempt reached. A limit below one worst-case proposal turns the runs the ladder exists for into budget escalations.

Part 3 drew the line between sensor and bound that this rests on. A task budget is a sensor, and observed spend is the right way to size it. A spend ceiling is a bound, so derive it from the work it bounds, and use observed spend only to check that the derived number is not absurd.

Checking width found the other mistake. In its first draft, the book allowed 24 branches, because two years of monthly invoices is 24. Counting the proposal, 24 judge calls need 25 model calls, and the run allows 20. In the book's check, which counts the branches alone, the number reported is 24; either way, at its own maximum the fan-out could never fit in an empty run. Between 20 and 24 invoices, the width limit allowed the fan-out and the call ceiling refused it, so the refusal blamed model calls on a ticket whose real problem was width. With 16, the proposal and three retries still fit. One more interaction is on the last line of output. A proposal that climbed the whole ladder leaves 8 calls, so after it any fan-out wider than 8 is refused at lookup. Nothing in the ladder is cut: it finished, and the refusal happens at the next node with its reason. That is the intended behaviour, and the third ticket in the fan-out demo shows it firing at 9 invoices. The shipped limit fails the combined path, 12 ladder calls plus 16 judge calls against 20, on purpose, and the last output line writes the consequence down.

d2
direction: down
classes: {
  low: {style: {fill: "#E74C3C"; stroke: "#B03A2E"; font-color: "#FFFFFF"}}
  ok: {style: {fill: "#6BCF7F"; stroke: "#3F9E52"; font-color: "#2C2C2A"}}
  need: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
}
need: "One worst-case proposal: 12 calls x 0.096 = 1.152" {class: need}
limits: {
  grid-columns: 4
  grid-gap: 16
  label: "Cost limit per run"
  style: {fill: "#FFFFFF"; stroke: "#C9C9C9"; font-color: "#2C2C2A"}
  a: "3x typical\n0.063\nrefuses every run" {class: low}
  b: "5x typical\n0.105\nrefuses the ladder" {class: low}
  c: "about 29x\n0.60\nrefuses the ladder" {class: low}
  d: "derived\n1.50\npays for it" {class: ok}
}
need -> limits

Only the derived limit clears the bar, and the bar comes from declared numbers: the call shape, its dated prices, the ladder's length and the retry count. Observed spend never enters it.

In the research for this part, no public incident turned up in which a hard limit sized from observed spend cut off a legitimate run, so the case above is the book's constructed one, and I label it that way. Its opposite is well documented: a cap that sits below one unit refuses the job before it starts. The Token Budgets paper records it as its E8 condition, "Sub-floor cap: refusal-to-operate". Anthropic's task-budget page warns that a budget too small for the task "can cause refusal-like behavior".

Fleet-wide LLM budgets: hold the reservation in a shared ledger

Inside one run, a reservation can be a projection, checking the totals plus the worst case and then spending, as long as every parallel step is opened by a node that reserves for all of it. A fan-out does that in one call before any branch exists. Two reserving nodes that LangGraph runs in the same superstep would read the same snapshot, exactly as the branches did, so the graph should not contain them. Nothing in this design checks that today. It is a review rule, and a startup check over the compiled graph could enforce it. Across runs, other runs spend at the same moment. Two runs that project against the same balance at the same time both pass, which is the Token Budgets paper's 30 of 30 one level up. A fleet limit has to take the amount out of the balance and hold it. Every run under its own ceiling with the fleet unbounded is Part 8's Budget Amnesia at fleet scope: the budget is held by objects that live for one run, and the scope it must bound is the night.

That is what the book's fleet ledger does. Each run places a hold for its own cost ceiling when it starts and commits what it really spent when it finishes. For the night, model spend is set to 120.00 and each run's ceiling to 1.50:

text
=== the fleet: 240 overnight runs, each reserving its own ceiling  headroom at 23:00: 80 runs at 1.50 each  run-80: fleet-cost: run-80 needs 1.50; the window has 0.00 of 120.00 left  started 80  40 finish at 0.021 each; headroom 39  23:31, the other 40 never reported back; holds expire; headroom 79

Nobody set 80. It is the remaining fleet budget divided by the run ceiling, so the concurrency limit falls out of the ledger and grows as runs finish under budget. Run 80 is refused before it starts, which is the only cheap moment to refuse it. The price is over-reservation. Each run holds 1.50 and an ordinary one spends 0.021, about 71 times less, so early in the night the ledger caps the fleet at 80 runs that the money could have paid for many times over. The alternative is to reserve each call in the fleet ledger, as LiteLLM's proxy does. I keep per-run holds for two reasons: one ledger write per run instead of one per call, and a run that has started is never refused halfway through by another run's spending. That last line is the failure to design for. A run that dies while holding budget strands that budget. If the hold never expires, every later run is refused, and the dashboard reports that the budget is working. So holds expire. A hold that expires while its run is still alive gives that run's money to another run, so the book's loader also checks that the hold's lifetime, 30 minutes, is longer than the run's wall-clock limit of 90 seconds. These two errors are not equal. Living too long, a hold strands a dead run's 1.50 for half an hour; dying too early, it lets the fleet overspend. So the expiry errs long, and stranded holds are worth reporting as a signal.

An expired hold should not simply vanish, though. The book's run releases the 40 expired holds, which is how headroom returns to 79, and that books whatever those runs spent before they died as zero. A dead run may have spent up to its 1.50, because a model call is billed when it returns, not when the run reports. In production, expiry should commit the hold at its full amount, and reconciliation against the provider's usage report releases what the dead run did not spend. Reconcile each expired hold soon after it expires, from the run's journal or the provider's usage report. Otherwise the committed holds strand the budget for the rest of the night, exactly as holds that never expired would.

d2
direction: right
classes: {
  ledger: {style: {fill: "#4A90E2"; stroke: "#2C6FB0"; font-color: "#FFFFFF"}}
  run: {style: {fill: "#7B68EE"; stroke: "#5A4BC4"; font-color: "#FFFFFF"}}
  warn: {style: {fill: "#FFA07A"; stroke: "#C96F4A"; font-color: "#2C2C2A"}}
}
start: "Run starts\nhold its ceiling: 1.50" {class: run}
ledger: "Fleet ledger\nlimit - committed - held\none conditional write" {class: ledger}
finish: "Run finishes\ncommit 0.021\nrelease the rest" {class: run}
dead: "Run dies\nhold expires after 30 min\n(longer than the 90 s run limit)\ncommitted until reconciled" {class: warn}
start -> ledger: "reserve"
ledger -> finish: "settle"
ledger -> dead: "no report"

In production the ledger is a row per hold in a database the whole fleet shares, and the reservation is a single conditional write that inserts the hold only if committed spend, plus spend already held, plus this amount stays within the limit. Written as read, compare and then write, a reservation races in exactly the way the projection did. Because the ledger is also on the path of every run, it must fail closed: if it cannot be reached, it refuses new runs rather than admitting them.

A vendor's per-worker cap misleads here too. As quoted in its issue #1107, the Agentfield blog said that "eight workers at $1.50 each can never cost more than $12, no matter how badly one of them loops." Each of those caps is a Receipt Ceiling, so the real worst case is the sum of the caps plus, for each worker, its largest call times the calls it can have in flight. In the same issue, a $1 cap was measured stopping at $3.015, on a stand-in API with the same caveat as #100111. Managed Agents describes the same arithmetic for its own threads: one request of overshoot for each thread. A fleet held in one ledger has neither problem, as long as an expired hold is committed rather than forgiven, because every run's worst case is held before the run spends anything.

Even this ledger has a limit of its own. A provider's spend cap sees one provider and one currency of spend. It cannot count a refund, a lookup against your billing API, or a fallback model from another provider. In the fleet ledger the problem is the opposite: it counts whatever the harness writes into it, and only that. Reconcile its committed total against the provider's invoice every month. According to the provider's pricing page, Claude 4.7 and later models also use a tokenizer that "produces approximately 30% more tokens for the same text", so a model upgrade can move cost per run with no change to the price table.

How to test an LLM spend limit: what it refuses and what it counts

A test that only checks the limit fires when exceeded passes for the opening's tool-call ceiling. That ceiling would refuse correctly at twelve, and it counted none of the 31 lookups. So a ceiling needs two tests. One checks that it refuses the unit that would cross, at the point where a receipt would still pay. Another checks that it counts what it claims to count. Against the demo's functions:

python
from decimal import Decimalimport pytestfrom receipt_vs_reservation import BoundExceeded, receipt, reservationdef test_the_reservation_refuses_what_the_receipt_pays() -> None:    moved = Decimal("120.00")    receipt(moved, Decimal("40.00"), Decimal("40.00"))  # passes: 120.00 < 150.00    with pytest.raises(BoundExceeded):        reservation(moved, Decimal("40.00"), Decimal("40.00"))@pytest.mark.parametrize("proposed", ["0.01", "10.00", "49.99"])def test_the_reservation_reads_neither_amount(proposed: str) -> None:    with pytest.raises(BoundExceeded):        reservation(Decimal("120.00"), Decimal(proposed), Decimal(proposed))

Both tests pass with pytest. Of the two, the second keeps the reservation a bound. If someone later lets the proposed amount make a refund affordable, a proposal of 0.01 gets through and the test fails. On the wired graph, the book's suite carries the counting half. At the end of a run, the budget must equal a fresh total computed from the journal, and the harness's depth must equal LangGraph's superstep count. It also pins three framework facts that this design depends on: branches that write a plain field raise InvalidUpdateError, a wide fan-out costs the recursion limit one step, and the default recursion limit is 10007. When a LangGraph release changes one of them, the suite fails before production does.

How to size an LLM agent budget from declared worst cases

Every failure in this part is a check that read a number it was never given. No branch could write the tool-call ceiling's counter, so the ceiling counted none of the lookups. Under a receipt, and under a check run separately in each of 31 branches, the missing number was the same one: the size of what was about to be spent. Sized from ordinary runs, the 0.60 limit had a different gap: it knew nothing about the one run that needs the whole ladder. In each case, the fix is to give the check the number it needs before the unit runs: the most that unit can cost, from a file somebody wrote and dated. After the unit runs, record what it really cost. Vendor advice to leave headroom is a correct description of the Receipt Ceiling. What it asks for is at most one worst-case unit per thread in flight, and a reservation holds that amount before the unit runs instead of hoping a margin covers it. Because every one of those amounts is declared, the loader rejects the 0.60 limit before a single run, as it rejected the first draft's 24-branch width.

Checklist: spend limits for an agent run

  1. Find every limit you rely on and write down what it reads. If it reads spend already incurred, it is a Receipt Ceiling, and its overshoot is the largest unit it admits.
  2. For count meters with units of one, outside a fan-out, a pre-check of count + 1 > limit is already exact. Spend your effort on money, tokens, refund amounts and fan-outs.
  3. Give every node that makes a model call a declared call shape: model, maximum input tokens, maximum output tokens. Refuse to load a node that has none. A fallback model gets its own call shape, priced and reserved like the primary's.
  4. Keep a price table with a verified date and a source URL, and price cache writes in it for any node that writes the cache. Treat a price change like any other change to the system, and re-run the startup checks.
  5. Take the worst case of a money tool from the approval gate's band, through the same function the gate uses. Do not declare it a second time in the budget file.
  6. Reserve before the unit runs: totals plus the declared worst case, against every limit for the mode. Refuse and escalate with the reason. Do not truncate the work.
  7. Settle each unit from the provider's reported usage into an append-only journal. Compute the budget from the journal, and test that the two agree.
  8. Never check a branch against the state snapshot it was sent. Reserve the whole fan-out at the node that opens it, width times the branch's worst case, or have each branch reserve against a shared ledger with one atomic conditional write.
  9. At startup, check that the cost limit pays for one worst-case proposal, ladder included, priced on every model the node may run, primary and declared fallbacks. Check that each fan-out fits in an empty run at its own maximum width. Then write down how wide a fan-out can be after a full ladder, so that refusal is known rather than discovered.
  10. Compute recursion_limit from the depth ceiling, with room for the refused step and the walk to escalation.
  11. Hold fleet budget in a shared ledger with one conditional write per reservation. Expire holds, make the expiry longer than the run's wall-clock limit, commit an expired hold at its full amount until reconciliation releases it, and fail closed when the ledger cannot be reached.
  12. Emit every refusal with the ceiling's name, the meter, the balance and the reservation, into Part 6's Second Stream beside the run's other decisions. Watch the share of runs that end at each ceiling. A share near zero for months means the ceiling is generous or dead. A share that jumps after a deploy means a layer upstream started spending more.

Harness Engineering book, Chapter 13: Cost, Depth, Width

This is Part 13 of a series that follows Harness Engineering for Production AI Systems one chapter at a time. Chapter 13, "Cost, Depth, Width," starts from a search of the companion package for every write to the run's budget, which finds four of its six counters never written at all. It refactors those counters so each one means one thing, and derives the recursion limit from the depth ceiling, with the measurement behind each of the three added steps. It runs all four startup checks against the other policy files, attributes spend to the component that caused it, and covers per-tenant ceilings and the provider's own budgets in more depth than this part does. In the chapter, the Managed Agents session cap is called "a real bound". By the chapter's own definition, and by the overshoot that the current documentation states, it is a Receipt Ceiling. Code for the chapter is in the ch13-cost-depth-width tag of the companion repository.

References


Agentic AI

Follow for more technical deep dives on AI/ML systems, production engineering, and building real-world applications:


Books by Ranjan Kumar

Federated AI Agents cover

Federated AI Agents

Right-Sized AI cover

Right-Sized AI

Harness Engineering for Production AI Systems cover

Harness Engineering

The 7 GenAI Architectures cover

The 7 GenAI Architectures

Building Real-World Agentic AI Systems with LangGraph cover

Building Real-World Agentic AI Systems

The ChatML Handbook cover

The ChatML Handbook

The Chat Templates Handbook cover

The Chat Templates Handbook

Comments