Procedure · 6 steps
- 1Set a run envelopeDerive a dollar limit per agent run from the price of the task to the customer and your margin target.
- 2Split it across rolesGive the planner, each worker sub-agent and a reserve their own share of the run envelope.
- 3Propagate the run identityPass the same tenant and run identity on every model call made by every sub-agent so the gateway can sum their spend.
- 4Check in the orchestratorBefore each step, compare remaining envelope with the expected cost of the next call and stop or ask the user when it is too low.
- 5Enforce in the gatewayConfigure the envelope as a gateway policy so calls are refused once the run total exceeds it, even if orchestrator logic fails.
- 6Review overrunsInspect runs that hit their envelope weekly and adjust the split or the task design.
Multi-agent systems multiply cost in a way single agents do not. A planner spawns workers, workers call tools and sometimes spawn their own helpers, and every one of them carries context into every call. Per-tenant budgets catch the monthly total, and loop breakers catch pathological behavior, but neither answers the question a product needs answered per task: how much is this run allowed to spend? Budget envelopes answer it.
Step 1: set a run envelope
Start from what the task is worth. If a research report is part of a plan that allows 40 reports a month for $199, and your margin target leaves about a quarter of revenue for model cost, the model budget per report is roughly $199 x 0.25 / 40 = $1.24. Leave headroom for variance and set the envelope at about twice that.
In the example in the snapshot the envelope is $2.50 for a run.
Step 2: split by role and keep a reserve
Give the planner a fixed share, $0.40 here, because planning is short but often uses the strongest model. Hold a reserve of $0.30 for the final synthesis step, so a run that spent heavily on research can still produce an answer. Split the rest evenly across workers: ($2.50 - $0.40 - $0.30) / 4 = $0.45 each.
At 20k input and 1.2k output tokens per worker call on Claude Sonnet 4.5, a worker call costs $0.0780, so each worker can make 5 calls. That number is your design constraint: if a worker routinely needs more, the task design, the context size or the model choice should change, not the envelope.
Step 3: propagate identity
Every model call made on behalf of the run, by any sub-agent, must carry the tenant and the run identity. In practice that means passing a context object through the orchestrator rather than creating fresh clients inside each worker. The PALM SOUQ SDK attaches tenant, feature and run context to every call made from a scoped client.
from palmsouq import PALM SOUQ
tg = PALM SOUQ(provider="anthropic")
with tg.envelope(tenant="acct_4471", feature="research_report", run_id="run_7731", usd=2.50) as run:
plan = run.child("planner", usd=0.40).messages.create(model="claude-sonnet-4.5", messages=plan_msgs, max_tokens=2000)
for i, task in enumerate(plan_tasks(plan)):
worker = run.child(f"worker_{i}", usd=0.45)
result = worker.messages.create(model="claude-sonnet-4.5", messages=task, max_tokens=1200)Step 4: check in the orchestrator
Before each step, the orchestrator compares the remaining envelope with the expected cost of the next call, estimated from the context size and the model price. If the remaining budget is too low, it can summarize context to shrink the next call, switch the worker to a cheaper model, skip optional work, or stop and report partial results. These choices belong to the application, because only it knows what partial success looks like.
Step 5: enforce in the gateway too
Orchestrator checks fail when the orchestrator has a bug, and loops are bugs. The gateway enforces the same envelope independently: once the summed cost for the run exceeds the envelope, further calls for that run are refused with HTTP 429 and X-PalmSouq-Reason: circuit_breaker_triggered. The orchestrator then handles that refusal like any other terminal condition.
Step 6: review overruns
- Runs that hit the envelope: which role ran out, and was the result still useful?
- Runs that used less than a quarter of the envelope: the envelope may be too generous to catch a real problem early.
- Cost per successful run by tenant: the number that belongs on the margin dashboard.
Meera Krishnamurthy
CTO, PALM SOUQ
IISc (MTech, CDS). Built low-latency edge proxies at a CDN provider and rate-limiting infrastructure for a payments network handling 9,000 TPS. Owns the gateway and breaker engine.