docs

Governance & Budgets

Set hard limits on agent spending, tool calls, and run behavior — globally or per agent using the governance block.

Full governance config

agentfile.yaml
governance:
  max_budget_per_run: 0.50       # USD — agent stops when this is exceeded
  human_approval:
    enabled: true
    actions: [file_write, send_email, shell_exec]
  rate_limit: "10_requests_per_minute"

Budget limits

max_budget_per_run sets a USD ceiling per run. Token costs are computed using built-in model price tables (input + output tokens × per-million price). When 80% of the budget is consumed a budget_warning event is emitted and a warning is printed to stderr. When the limit is exceeded the agent raises BudgetExceededError, emits a thread_budget_exceeded event, and stops gracefully.

Set AGENTFILE_SHOW_COST=1 to print per-call cost and running total to stdout at runtime.

Per-agent budgets
Set different budgets for different agents. A writer agent might have a higher budget than a quick lookup agent.

Per-agent overrides

YAML
governance:
  max_budget_per_run: 0.10     # global default

agents:
  orchestrator:
    governance:
      max_budget_per_run: 1.00  # orchestrator gets more budget
      human_approval:
        enabled: true
        actions: [send_email]

  quick-lookup:
    governance:
      max_budget_per_run: 0.02  # strict limit for cheap tool

Rate limits

rate_limit uses a token-bucket algorithm. Supported formats: "10_requests_per_minute", "2_requests_per_second", "10_rpm", "2_rps". The agent sleeps automatically when the bucket is empty and prints a [rate-limit] warning to stderr.

View token usage

Every checkpoint stores tokens_used, input_tokens, output_tokens, run_cost_usd, and budget_usd. The dashboard shows token and cost data per run and per step.

On this page