ACAgentic Craft

Intermediate~12 minHazelJS

Budget-Aware Execution

Enforce hard economic stops with RunBudget maxTokens/maxCostUsd plus maxSteps—budgets that live in AgentRuntime, not in prompt text.

Authors
editorial-team
Published
Last reviewed

Problem

Token/cost limits written only in prompts are ignored when the model loops; overnight demos burn monthly spend.

Context

Any AgentRuntime.execute path in shared environments, multi-tenant apps, or CI with live providers.

Forces and constraints

  • Open loops have unbounded worst-case cost
  • Finance needs enforceable ceilings
  • Operators need a clear BUDGET_EXCEEDED stop reason
  • Step count and token/cost limits solve different failure modes

Recommended design

Pass RunBudget on execute (`budget: { maxTokens?, maxCostUsd? }`) and/or defaultBudget on the runtime. Separately set maxSteps (execute option or @Agent). On exceed, runtime stops with a persisted budget stop reason—do not rely on the model to ‘notice’ the budget. Combine with cost routing / GovernanceGate where documented.

Minimal pseudocode

await runtime.execute('researcher', goal, {
  maxSteps: 12, // step ceiling — not a RunBudget field
  budget: {
    maxTokens: 80_000,
    maxCostUsd: 1.0,
  },
});

// Optional: runtime defaultBudget for all executes
// Listen/alert on BUDGET_EXCEEDED in observability

Failure modes

  • Only maxSteps set — cheap but endless tiny calls still add up if mispriced
  • Only maxCostUsd — provider pricing drift surprises finance
  • No alert on budget exhaustion — silent user failures
  • Shared budget across tenants without attribution

Security considerations

  • Budgets are not auth — still enforce capabilities/policies
  • Prevent tenants from raising ceilings without approval

Observability signals

  • Metric: budget_exceeded_count by agent
  • Export tokens/USD on AgentRun timeline
  • Alert when weekly spend > threshold

Evaluation approach

Fixture that forces a long tool loop under a tiny maxTokens and asserts clean stop; cost regression in CI with assertAgentResult maxCostUsd.

Trade-offs

  • Tight budgets increase partial-answer rate
  • Loose budgets recreate demos-as-prod risk

Sources

Related patterns