Cost control

Gate a pipeline on budget covers budget.max_usd — a hard backstop that aborts a run after it’s already gotten expensive. This guide is about the design choices that decide how expensive a pipeline gets before that backstop is ever needed.

A budget cap is a backstop, not a strategy

budget.max_usd/max_tokens catches a runaway run — a loop, a tool returning far more than expected, a genuinely pathological case. It does nothing about a pipeline that’s reliably, unremarkably expensive every single time it fires, because a run that costs exactly what you’d expect never trips it. The rest of this guide is about that second problem: the choices made once, at authoring time, that set the steady-state cost a budget cap never sees.

Model selection is the biggest lever, by far

Writing good agents’s “match the model to the job” principle is a cost argument as much as a quality one. A first-line triage step run 200 times a day paying frontier-model rates on every run adds up in a way a single expensive step never does — set a cheap default model in the agent’s own config, and override it per step with executor_config.model for the one step (often a verifier, or a step whose mistakes are genuinely expensive) where the stronger model is actually earning its keep. This is a decision worth revisiting per step, not a single global setting: the cheapest model that reliably does the job is the right default everywhere it holds, and the exception should be narrow and named, not “use the best model everywhere just in case.”

An accurate confidence threshold saves money, not just catches errors

A step that escalates early on genuinely low confidence avoids paying for however many expensive downstream steps would otherwise have run on a shaky foundation — a triage step that should have escalated but didn’t doesn’t just risk a wrong answer, it pays for every step built on top of it. Choosing confidence thresholds covers picking the number; the cost argument is the same “don’t guess, calibrate” advice with a dollar figure attached — a threshold set too low isn’t just a correctness risk, it’s a standing invitation to keep spending on work that was never going to be trustworthy.

Verifier mode is a cost/rigor trade-off

critic re-reads what the primary already produced against its own trace; independent redoes the entire task from scratch, blind — roughly doubling that step’s cost for the stronger, uncorrelated corroboration signal. Verifiers frames the choice around correlated vs. uncorrelated errors; priced, it’s the same choice: pay double for a step that authorises a real side effect, stay cheap for a step that only informs the next one. A band-based trigger (confidence_below/ confidence_above) is the other half of this lever — a verifier that only fires in the genuinely uncertain middle, rather than on always: true, pays for a second opinion only on the runs that actually need one.

Grounding is cheap if the judge is

Writing your grounding judge’s model-choice advice applies directly here — cross-referencing a claim against a transcript is a constrained, mechanical task that doesn’t need a frontier model, so a grounding judge is one of the cheapest ways to add a trust signal, provided you pick a cheap model for it. It’s also not optional spend you can defer: shadow mode means the judge call runs and is priced on every step that declares grounding:, whether or not enforce: true is set — you’re already paying for it before you’ve decided whether to gate on it, which is exactly why the model choice matters from the start rather than being tuned later.

max_items on a fan-out is a direct cost cap

N branches means N LLM calls, run concurrently — fan-out’s max_items guardrail (default 20) is as much a cost control as a safety one, worth setting deliberately rather than leaving at the default for a step whose list could plausibly be much longer. It compounds fast: a fan-out branch that also carries a verifier: and a grounding: block multiplies per branch, not just per step — up to 2× max_items extra model calls on top of the primary ones, so a max_items: 20 fan-out with both configured can mean 60 model calls for what reads, in the YAML, like one step.

Team budgets tell you about a trend; max_usd stops one run

pricing.team_budgets is advisory, month-to-date, and never blocks anything — it exists for noticing a team’s spend is climbing before it’s a crisis, surfaced on /ui/insights/teams and the vectorstep_team_budget_ratio gauge. budget.max_usd is the emergency brake for one run, and enforcement stays there deliberately: blocking a critical-alert triage because a calendar month happens to roll over would be the wrong failure mode for an ops tool. Neither substitutes for the other — a team can be well under its monthly budget while a single run still needs a hard ceiling, and a team trending over budget is a conversation about which pipelines to revisit, not something a per-run cap can fix on its own.

Unpriced spend is invisible spend

A model with no pricing.models entry (and no live pricing match) contributes NULL to every rollup, never 0 — NULL means “unknown,” not “free,” and a NULL cost never counts toward budget.max_usd regardless of count_pricing, so an unpriced model can run indefinitely without ever tripping the guardrail you thought was watching it. Cost control starts with the pricing table actually covering what’s really running: a manual pricing.models entry for anything you have a real rate for, or opting into pricing.live_pricing so an unpriced model at least shows up as a live estimate — cross-provider if needed — instead of a silent gap. See Cost accounting for how the three tiers resolve and which one a run’s budget: actually trusts.

Where next

• Cost accounting — the full pricing table, budget guardrail, and team-budget reference this guide draws its mechanics from.
• Gate a pipeline on budget — the hands-on backstop this guide’s opening section refers to.
• Writing good agents — the quality-first framing of the same model-selection argument.
• Choosing confidence thresholds — picking the number this guide’s threshold section assumes.
• Verifiers — the full critic/independent and trigger-band reference behind the verifier cost trade-off above.