feat: @budget decorator for Flows — cost, token & request limits with HITL approval

[alex-clawd]

Summary

This PR introduces a native Budget decorator for CrewAI Flows, enabling cost, token, and request limit enforcement with human-in-the-loop (HITL) approval when limits are exceeded.

Key Features

• @budget decorator for Flow methods with configurable limits:

  • max_cost: Maximum cost in USD
  • max_tokens: Maximum total tokens
  • max_requests: Maximum LLM request count (NEW)
  • on_exceed: Action when limits are exceeded ('pause', 'stop', 'warn')

• Custom pricing support (NEW):

  • cost_per_prompt_token / cost_per_completion_token: Flat per-token pricing
  • cost_map: Per-model pricing overrides
  • Priority: flat pricing > cost_map > DEFAULT_MODEL_COSTS

• Comprehensive token tracking:

  • Registers event listener on LLMCallStartedEvent to count LLM requests
  • Extracts usage from CrewOutput, LiteAgentOutput, and any object with token_usage or usage_metrics attributes
  • Works with direct LLM calls, agent kickoffs, and crew kickoffs

• Three enforcement modes:

  • 'pause' (default): Uses existing HITL infrastructure to request human approval to continue
  • 'stop': Raises BudgetExceededError immediately
  • 'warn': Logs warning and continues execution

• Better HITL approval UX:

  • Shows current spend breakdown (cost, tokens, requests)
  • Indicates which limit(s) were hit
  • Supports approving specific additional amounts

API

@budget(
    max_cost: float | None = None,           # USD cap
    max_tokens: int | None = None,           # total token cap
    max_requests: int | None = None,         # LLM request count cap (NEW)
    on_exceed: 'pause' | 'stop' | 'warn' = 'pause',
    cost_per_prompt_token: float | None = None,      # custom flat pricing (NEW)
    cost_per_completion_token: float | None = None,  # custom flat pricing (NEW)
    cost_map: dict | None = None,            # per-model pricing override
)

Usage Example

from crewai.flow import Flow, start, listen, budget

class BudgetedFlow(Flow):
    @start()
    @budget(max_cost=5.00, max_requests=10, on_exceed='pause')
    def run_expensive_task(self):
        crew = MyCrew()
        return crew.kickoff()

    @listen(run_expensive_task)
    def process_results(self, result):
        # Access budget summary
        print(f"Total cost: ${self.budget_summary['estimated_cost']:.2f}")
        print(f"LLM requests: {self.budget_summary['total_requests']}")
        return result

# Custom pricing for negotiated rates:
@budget(
    max_cost=10.00,
    cost_per_prompt_token=0.000003,   # $3/1M tokens
    cost_per_completion_token=0.000015,  # $15/1M tokens
)
def custom_priced_task(self):
    ...

Breaking Changes

• Renamed @cost_governor → @budget
• Renamed CostGovernorConfig → BudgetConfig
• Renamed CostTracker → BudgetTracker
• Renamed cost_summary → budget_summary
• Renamed parameters: budget_limit → max_cost, token_limit → max_tokens

Backwards-compatible aliases are provided: cost_governor, CostGovernorConfig, CostTracker

New Exports from crewai.flow

• budget: The decorator
• BudgetConfig: Configuration dataclass
• BudgetTracker: Internal tracking class (for advanced use)
• BudgetExceededError: Exception raised when limits exceeded and denied/stopped

Test Plan

• Test max_cost triggers pause/stop/warn
• Test max_tokens triggers pause/stop/warn
• Test max_requests triggers pause/stop/warn (NEW)
• Test request counting via event listener (NEW)
• Test custom flat per-token pricing (NEW)
• Test cost_map per-model overrides (NEW)
• Test flat pricing overrides cost_map (NEW)
• Test combined limits (cost + tokens + requests — first one hit triggers)
• Test budget_summary includes request data (NEW)
• Test cost accumulation across multiple method calls
• Test approved continuation increases limits
• Test denied continuation stops flow
• Test with async flow methods
• Test decorator preserves flow attributes (@start, @listen, etc.)
• 63 comprehensive tests pass
• 67 existing flow tests pass

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds new opt-in runtime governance around LLM usage by hooking into the global event bus and Flow method wrapping, which could affect execution timing and accounting (especially with concurrent flows) if misconfigured.

Overview
Introduces a new @budget decorator for Flow methods that tracks token usage, estimated cost, and LLM request count, then enforces configurable limits via warn, stop (BudgetExceededError), or pause (HITL approval) behavior.

Budget tracking is integrated into Flow via a per-instance tracker and a new budget_summary property, and Flow method wrappers now preserve __budget_config__ metadata. The implementation adds event-bus listeners (LLMCallStartedEvent/LLMCallCompletedEvent) to count requests and capture per-call token deltas, with support for custom pricing (cost_map or per-token rates) and comprehensive new tests covering sync/async paths and approval/denial flows.

^{Written by Cursor Bugbot for commit 3ac17a4. This will update automatically on new commits. Configure here.}

[cursor]

HITL approval message shows wrong budget limit

Medium Severity

The HITL approval message displays tracker.max_cost (the original budget) instead of tracker.effective_budget (which includes previously approved amounts). After a first approval (e.g., max_cost=$5, approved_budget=$5, effective_budget=$10), if the budget is exceeded again at $12, the message says "cost ($12.00 >= $5.00)" and "$5.00 budget" — implying the limit was $5, when the actual enforced limit was $10. This gives the human reviewer incorrect information to base their approval decision on.

Additional Locations (1)

• lib/crewai/src/crewai/flow/budget.py#L452-L453

 

[cursor]

Negated approval phrases falsely match as approved

Medium Severity

The feedback text parsing checks approval patterns before denial patterns, so negated phrases like "not ok", "not okay", or "no, ok fine" incorrectly match the approval regex (\bok\b / \bokay\b) and are treated as approval. Since the approval pattern is checked first and short-circuits, the denial keyword is never evaluated. This could cause unintended budget continuation with real cost implications.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Unused cfg parameter in _create_completion_tracker

Low Severity

The cfg: BudgetConfig parameter of _create_completion_tracker is never referenced in the function body or its inner handler closure. It's passed at both call sites (lines 883 and 905) but serves no purpose, adding unnecessary noise to the interface.