How to Give Your AI Agent a Budget (Without Losing Sleep)

June 11, 2026 · Victor Young

Giving an AI agent a budget means configuring a hard spend limit that the agent cannot exceed—no matter what it finds, no matter how good the deal looks. A spend limit is not a suggestion; it is a constraint enforced at the execution layer before any payment is authorized. When done correctly, budget controls let you delegate purchasing decisions to an agent with confidence, because the worst-case financial outcome is known before the execution starts.

Why Informal Budget Controls Fail

The intuitive approach to agent budgeting is to put the constraint in the prompt: "find noise-cancelling headphones, stay under $80." This works until it does not. Language models can miscount, misinterpret currency, or simply generate an output that exceeds the constraint because the model weighted other factors—quality, availability, user preference—above the dollar limit.

Prompt-level budget guidance is a hint. You need an enforcement layer.

The right architecture puts the spend limit in the API request, not the prompt, so it is evaluated by deterministic code rather than probabilistic inference. The agent's natural-language request guides intent; the structured budget parameter enforces the financial constraint regardless of what options the agent might otherwise prefer.

This is the same principle that makes approval checkpoints work: the control lives outside the model, in infrastructure that does not hallucinate.

The `budget` Object

In Firestarter, every execution request accepts an optional budget object. The simplest form is a single max_total field:

{
  "request": "noise cancelling headphones under $80",
  "budget": {
    "max_total": 80
  }
}

This tells the execution engine: do not surface, approve, or pay for any option whose total landed cost—including shipping and tax—exceeds $80. Options above the limit are filtered out before the results reach the human approval gate. You never see a $95 option and have to say no; it is not there.

max_total is a hard cap on total landed cost, not unit price. This distinction matters. A product listed at $72 with $12 shipping has a landed cost of $84, which exceeds an $80 limit. An agent without this constraint would surface it anyway and leave you to do the math. With max_total, the $84 option is excluded automatically.

Shipping Is Part of the Budget

The most common failure mode in agent budget controls is forgetting shipping. A spend limit set on item price alone is not a spend limit—it is a floor on the final charge.

Firestarter's max_total budget covers:

Item price (including quantity × unit price for bulk orders)
Shipping and freight
Applicable taxes

When the agent compares options, it calculates total landed cost for each and rejects any that exceed max_total. The comparison payload shown to the human approver displays landed costs explicitly so there is no ambiguity.

For bulk B2B orders, this behavior is especially important. In the kraft mailer boxes scenario, an order for 500 mailer boxes might have a unit price that looks affordable but a freight charge that pushes the total over budget. The max_total constraint handles this correctly because it operates on the complete cost, not just the line item.

Approval Thresholds as a Second Layer

A spend limit defines the ceiling. An approval threshold defines when a human must review before the execution proceeds. These are separate controls that work together.

A common pattern: set a spend limit at the organizational budget for the category, and set an approval threshold below it so that anything above routine spend gets reviewed.

{
  "request": "ergonomic desk chair for new hire",
  "budget": {
    "max_total": 600
  },
  "approval": {
    "required": true,
    "notify": ["ops@example.com"]
  }
}

Here the agent will not spend more than $600, and a human at ops@example.com must confirm before payment proceeds. The approval gate ensures a human sees the actual option selected and its total cost—even when that cost is well within the spend limit—before money moves.

For organizations with tiered approval policies (routine purchases auto-proceed, larger ones escalate), the calling system can set "required": false for executions below a threshold and "required": true above it, with different notify addresses for different escalation paths. See the developer docs for full approval configuration options.

Escrow: Money Only Settles on Delivery

A spend limit controls how much can be authorized. Escrow controls when that authorization converts to an actual charge.

Firestarter processes payment via Stripe, held in escrow at the moment of purchase. The funds are authorized—they are committed—but they are not captured until delivery is confirmed. If the order is cancelled before shipping, the authorization is released and no charge appears. If the order ships but is never delivered, the escrow provides a clean path to refund without a chargeback dispute.

This matters for agent budgeting because it means the financial exposure at any moment is transparent. If an agent places an order and the item is in transit, the escrow record shows exactly what is committed and what has settled. There are no surprise captures.

The escrow model also changes the risk calculation for granting agents higher spend limits. An agent with a $500 spend limit backed by escrow has a known maximum exposure of $500, and that amount is only captured when you have confirmed receipt of goods. Compare that to a card-on-file agent where the charge happens at order time with no delivery verification—there the financial risk is realized immediately.

Setting Budget at Different Levels of the Stack

Budget controls can be applied at several points:

Per-execution — Set max_total in each individual execution request. This is the most granular approach and the right default. Each use case gets its own spend limit tuned to what is appropriate.

Per API key / application — Configure a default spend limit at the workspace level in your account settings. All executions under that key inherit the default unless overridden in the request. Useful for ensuring that no agent using a given key can exceed a category budget, even if the individual execution does not specify one.

Conditional on approval — Use the approval gate as a budget enforcement mechanism: set the spend limit high, but require approval for anything above a lower threshold. The agent can always proceed up to the threshold without review; everything above requires a human.

A Full Request with Budget Controls

Here is a complete execution request with spend limit, approval, and preference constraints:

curl -X POST https://api.firestarter.network/v1/executions \
  -H "Authorization: Bearer fs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "500 kraft mailer boxes 10x8x4 for our Austin TX warehouse",
    "budget": {
      "max_total": 250
    },
    "preferences": {
      "delivery_by": "2026-06-18",
      "prefer_domestic_suppliers": true
    },
    "approval": {
      "required": true,
      "notify": ["warehouse-ops@example.com"]
    }
  }'

The agent will search suppliers, filter out any options with a total landed cost above $250, present the qualifying options to the approver at warehouse-ops@example.com, and wait for confirmation before payment. The approver sees total costs that already include shipping and freight to Austin TX.

See the kraft mailer scenario for the full end-to-end flow on this example, including how the agent handles bulk pricing tiers.

Using Budget Controls with MCP

If you are connecting Firestarter to a language model via the MCP integration, budget parameters are passed as part of the firestarter_execute tool call. The model can be instructed to always include a max_total budget based on the category or the user's stated preference:

claude mcp add firestarter \
  --transport sse \
  --url https://api.firestarter.network/mcp \
  --header "Authorization: Bearer fs_live_YOUR_KEY"

Once connected, the model has access to firestarter_execute, firestarter_status, firestarter_approve, firestarter_cancel, and firestarter_message. Budget configuration is part of the firestarter_execute call, so you can encode spend limit rules in the system prompt and rely on the execution layer to enforce them deterministically.

For a comparison of how Firestarter's budget controls compare to payment-only approaches, see Firestarter vs. Stripe Agentic Commerce and the agent action API use case page.

FAQ

What happens if all options exceed the spend limit?

If no supplier option falls within the max_total budget, the execution moves to a no_options status and notifies the requester. No payment is initiated. The agent reports back the lowest-cost option found and how much it exceeded the budget, so you can decide whether to raise the limit or adjust the request.

Does `max_total` apply to the entire order or per-unit?

max_total applies to the entire order—quantity multiplied by unit price, plus shipping and tax. For a request like "500 mailer boxes," it covers the total cost of the 500-unit purchase, not the cost per box. If you need per-unit constraints, include them in the natural-language request and in the preferences object.

Can I set different spend limits for different categories?

Yes. Spend limits are set per-execution, so different workflows can have different limits. An agent handling office supplies might have a $100 limit; one handling equipment purchases might have a $2,000 limit. Configure each limit in the execution request for that workflow.

Is the spend limit enforced before or after the approval gate?

Before. The execution engine filters options against max_total during the comparison stage, before options are presented at the approval gate. The human approver only sees options that already fit within the budget. This means the approval gate is never used to reject over-budget options—that work is done automatically.

How much does it cost to use Firestarter for budget-controlled purchases?

Free tier: 100 tokens to start plus a 14-day Pro trial, no credit card required. Pro is $99/month with 10,000 tokens. Buyers pay no transaction fees. See the pricing page for details.