Back to catalog / Agent operations

Set a USD budget cap for an agent run

Use max_budget_usd to cap a run’s cost and detect the budget-exceeded terminal status.

Goal

Set a cost guardrail for an agent that can call tools and perform multiple turns.

Set an approved USD limit with ClaudeAgentOptions(max_budget_usd=0.10). [budget]
Iterate the result stream and read ResultMessage.total_cost_usd and subtype. [budget]
Treat subtype == "error_max_budget_usd" as a budget stop and report partial output with actual cost. [budget]

A low-budget test identifies the budget status and records final cost instead of treating it as ordinary success.

If final cost slightly exceeds the cap, the README explains checks occur after each API call and may overshoot by one call; leave headroom.

The caller sets the budget policy; do not put user keys or billing details in agent prompts.

The budget cap is not a strict per-token hard stop, and budget termination does not roll back tool side effects.

These values describe the upstream repository, not popularity or likes for an individual skill or playbook.

No metrics snapshot is available yet.

License: MIT