Skip to main content

Budgets

Goal: cap what a flow or an agent may spend, and extend the cap when a person is asked.

Prerequisites​

  • A Flow or an Agent manifest to add the budget to.

Steps​

  1. Add a budget to the flow's spec (a ticket ceiling) or to an agent's spec (a per-agent ceiling). Every dimension is optional. An absent dimension is no limit:

    kind: Flow
    spec:
      budget:
        tokens: 200000
        toolCalls: 200
        costUsd: 5
        wallTime: 30m
        maxTurns: 40

  2. Set the alert fractions at which a person is asked, when the defaults (0.75, 0.9) do not fit:

    spec:
      alerts: [0.5, 0.9]

  3. Run the flow. The engine checks the budget against the ticket's ledger before each model call. It counts the tokens the next call would add.

  4. When an alert or a limit fires, the ticket pauses (paused_budget) and a person answers:

    afe resume T-0001 continue
    afe resume T-0001 extend
    afe resume T-0001 stop

    extend widens the dimension by half its limit. stop fails the ticket at that point.

See Budgets and loop guards for why the ledger is the source of truth, and Answer approvals for the other pauses.

Troubleshooting​

'agent' does not report its cost (reportsCost is not true) (a validation warning) An acp agent has a costUsd budget, but its AcpAgent manifest does not set reportsCost: true. The engine cannot check a cost ceiling it never receives. Set reportsCost: true if the agent reports cost, or drop costUsd from its budget.

The ticket pauses more often than expected A lowered alerts fraction fires earlier. Check the flow's alerts before assuming the ledger is wrong: afe inspect T-0001 shows the totals it paused on.

See also​