A Spend Cap Across Sub-Agents: When One Run Fans Out to Five

Take a parent run with a hard ceiling of $2.00 for one session. It spawns five children: a planner, a retrieval worker, two extraction workers, and a writer. Suppose the parent has already spent $0.20 on its own planning call. The remaining pool is $1.80.

A naive split of $1.80 across five children gives $0.36 each. That is fair in arithmetic and unfair in workload: the writer typically needs more output tokens than a retrieval worker. A better structure is a two-part allocation, a guaranteed share plus a claim on a shared pool.

Guaranteed shares total $1.30, leaving $0.50 in the pool. Total reserved capacity is $1.80, exactly the remaining budget. The pool is where fairness arguments actually happen, so the rule for spending it matters more than the initial split.

A workable decision rule: the pool is released to a child only when that child has consumed its guaranteed share, has a concrete pending call, and no sibling in a higher priority class is waiting. Priority classes are written in configuration, not chosen by the model. The writer outranks extraction, extraction outranks retrieval, and the planner is last. Ties within a class are broken by earliest request timestamp, then by child ID, so the outcome is deterministic and reproducible.

The reason to fix priority in config rather than let the agent decide is that the model should never choose its own gate. Finance control design makes the same point: limits should come from the delegation-of-authority policy and be written as fixed routing rules so the agent never decides its own gate Keboola's human-in-the-loop glossary. Fair division research reaches a parallel conclusion from a different direction: when agents have budget constraints, allocations must satisfy those constraints and naive envy-freeness often cannot be guaranteed, so you need an explicit, well-defined relaxation rather than an implicit hope Barman et al. on fair allocation under budget constraints.

A note on expectation setting: budget awareness changes behavior, not just accounting. Agents given more tool-call budget without any signal of how much remains tend to perform shallow work and saturate early; a lightweight budget tracker that continuously reports remaining resources produces better cost-performance curves Budget-Aware Tool-Use Enables Effective Agent Scaling. So expose the remaining pool to the child as context. It will plan differently.

Hold it in a shared durable store that every child reaches over the network, and treat that store as the only authority. Three placements work in practice; the choice is about failure modes, not elegance.

The last row is the strongest structural option, because it makes bypass impossible rather than merely discouraged. A gateway is described as the runtime control plane that turns policy into enforceable decisions across model calls, tool calls, and agent hops LangChain's governed-agents framework. If a child can call the provider directly with its own key, no counter you build will hold.

For most teams, start with the database. It gives you atomic transactions, row-level locks, and an audit trail in one system you already operate. The reserve table is small.

CREATE TABLE run_budget (
  run_id        TEXT PRIMARY KEY,
  ceiling_usd   NUMERIC(12,6) NOT NULL,
  reserved_usd  NUMERIC(12,6) NOT NULL DEFAULT 0,
  spent_usd     NUMERIC(12,6) NOT NULL DEFAULT 0,
  CONSTRAINT no_overspend CHECK (reserved_usd + spent_usd <= ceiling_usd)
);

CREATE TABLE reservation (
  reservation_id TEXT PRIMARY KEY,   -- idempotency key, generated before the call
  run_id         TEXT NOT NULL REFERENCES run_budget(run_id),
  child_id       TEXT NOT NULL,
  amount_usd     NUMERIC(12,6) NOT NULL,
  state          TEXT NOT NULL,      -- 'held' | 'settled' | 'released'
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

The check constraint is the last line of defense. It cannot stop a logical error in application code, but it makes an over-reservation physically impossible at the storage layer, which is exactly where you want the guarantee to live.

A note on the semantics of a ceiling. AWS documents its own throttles as applied on a best-effort basis and describes them as targets rather than guaranteed request ceilings the AWS API Gateway throttling docs. A spend cap should not carry that caveat. If your provider bills asynchronously, or if a call can be charged after your reservation is settled, then your reservation amount must be an upper bound, not an estimate of the mean.

The protocol has three steps and no exceptions. Reserve, call, settle.

Step 1, reserve. The child looks up its planned next call, computes an upper-bound cost from prompt tokens, max output tokens, and the provider's published rate, then writes a reservation. The write must be atomic: check available budget and insert the hold in the same transaction, or use a conditional update that fails when the check would break. The reservation ID is generated before the call and reused on every retry.

Step 2, call. If the reservation fails because the budget is exhausted, the child does not call the provider. It stops, records budget_exhausted, and returns whatever partial result it has. This is the whole point: the ceiling holds because spending requires a successful reservation.

Step 3, settle. On completion, the child writes the actual cost from the provider's response and converts the difference back to available budget. On a crash, a sweeper settles stale holds as released after a timeout, or as spent at the reserved amount if the provider confirms the call happened. Reservation records need an expiry: guidance on idempotency keys suggests keeping them long enough to cover typical retry windows and no longer the Zuplo guide.

def reserve(conn, run_id, child_id, amount, reservation_id):
    with conn.transaction():
        row = conn.execute(
            "SELECT ceiling_usd, reserved_usd, spent_usd "
            "FROM run_budget WHERE run_id = %s FOR UPDATE", (run_id,)
        ).fetchone()
        available = row.ceiling_usd - row.reserved_usd - row.spent_usd
        if amount > available:
            return False
        conn.execute(
            "INSERT INTO reservation (reservation_id, run_id, child_id, amount_usd, state) "
            "VALUES (%s, %s, %s, %s, 'held') ON CONFLICT DO NOTHING",
            (reservation_id, run_id, child_id, amount),
        )
        conn.execute(
            "UPDATE run_budget SET reserved_usd = reserved_usd + %s WHERE run_id = %s",
            (amount, run_id),
        )
    return True

def settle(conn, run_id, reservation_id, actual):
    with conn.transaction():
        held = conn.execute(
            "SELECT amount_usd FROM reservation "
            "WHERE reservation_id = %s AND state = 'held' FOR UPDATE",
            (reservation_id,),
        ).fetchone()
        if held is None:
            return  # already settled or released: safe on retry
        conn.execute(
            "UPDATE reservation SET state = 'settled' WHERE reservation_id = %s",
            (reservation_id,),
        )
        conn.execute(
            "UPDATE run_budget SET reserved_usd = reserved_usd - %s, "
            "spent_usd = spent_usd + %s WHERE run_id = %s",
            (held.amount_usd, actual, run_id),
        )

Two details in that code carry most of the safety. FOR UPDATE makes the read and the write one atomic step, which is the locking approach the idempotency literature prescribes for concurrent duplicate requests the Zuplo guide. And settle returns early when the reservation is not in held state, so a retried settle is a no-op rather than a double charge.

Instrument the path or you will not know which child ate the budget. Agent observability means capturing traces of execution flows, tool calls, and the parameters behind each action, so you can answer not just what happened but why Rubrik on agent observability. Microsoft's guidance adds evaluations and governance to the traditional metrics, logs, and traces trio Azure's agent observability practices. Practically: tag every reservation with run_id and child_id, and chart reserved versus settled by child. A child whose reserved amount consistently overshoots settled cost is wasting pool capacity that a sibling needed.

Run the worked example to the end and the rule becomes concrete. Suppose the parent spent $0.20, and the children consume as follows before any pool release: C1 used $0.06 of its $0.10, C2 used $0.19 of its $0.20, C3 used $0.30 of $0.30, C4 used $0.22 of $0.30, and C5 used $0.40 of $0.40. Settled child spend is $1.17, so the pool plus unused guarantees is $1.80 minus $1.17, or $0.63 available.

Now three children want more. C2 asks for $0.05, C4 asks for $0.10, and C5 asks for $0.30. Under priority ordering, C5 is first in line and takes $0.30, leaving $0.33. C4 is second and takes its $0.10, leaving $0.23. C2 is third and gets the $0.05 it asked for. Total new reservations are $0.45, the pool retains $0.18, and the absolute ceiling is untouched because every one of those three reservations passed the same check constraint.

Without a rule, the outcome is whoever asks first or whoever retries hardest. That is not fairness, it is timing luck, and it produces the noisy-neighbor problem that multi-tenant systems solve with layered limits and fair queuing Gravitee on rate limiting at scale. The priority class is the equivalent of a tenant tier.

Two guardrails make the rule survivable in production. First, cap any single pool release at a fraction of the pool, so no child can drain it in one call. Second, require human approval when a child asks to exceed its guaranteed share by more than a set threshold. Human-in-the-loop approval is the standard mechanism for pausing before a consequential action and resuming only on approval, and frameworks exist that implement the pause and resume natively Permit's human-in-the-loop guide. A pool release above the threshold is exactly that kind of action.

A warning about the alternative you may be tempted to build. Provider-side session budgets exist and are useful: LiteLLM tracks spend per session keyed by a trace ID and returns a 429 when a per-session dollar cap is exceeded the LiteLLM iteration and budget docs. Use it as a backstop. But a provider session counter is checked before a call and accumulated after it, which means it is a running total rather than a reservation, and concurrent children can each pass the check with the same headroom. The reserve table closes that window because the hold is committed before the call leaves your network.

Pricing accuracy deserves its own sentence. A cap is only as good as the rates behind it, and rates change. Store the rate you used with each reservation so a later review can tell whether an over-run was a logic bug or a stale price LangChain's governed-agents framework.

If you would rather not operate the reserve table, the gateway, and the settlement sweeper yourself, that is the layer Quanta Inference already provides: text, image, video, audio and embedding models through one API key, OpenAI-compatible, prepaid and priced in US dollars, at https://quantaintelligence.ai/inference. Prepaid balance plus one key per run gives you a hard boundary that no child can talk its way past, and you can still keep the reserve table for per-child fairness accounting on top of it.