cleveragents-core/docs/reference/cost_controls.md

Cost Controls

CleverAgents provides cost tracking, budget enforcement, and provider fallback controls for AI provider usage.

Configuration Keys

Key	Env Variable	Type	Default	Description
budget_per_plan	CLEVERAGENTS_BUDGET_PER_PLAN	float | None	None	Max USD spend per plan execution. None = unlimited.
budget_per_day	CLEVERAGENTS_BUDGET_PER_DAY	float | None	None	Max USD spend per calendar day. None = unlimited.
fallback_providers	CLEVERAGENTS_FALLBACK_PROVIDERS	list[str]	[]	Ordered provider fallback list. Empty uses default order.

Budget Thresholds

Threshold	Value	Behavior
Warning	90% of limit	Log warning, continue execution
Block	100% of limit	Block further provider calls, persist exhaustion event

Default Fallback Order

When fallback_providers is empty, the default order is:

1. OpenAI
2. Anthropic
3. Google
4. Azure
5. OpenRouter
6. Groq
7. Together
8. Cohere

Providers are skipped if they:

• Are not configured (no API key)
• Lack required capabilities (tool calling, streaming, vision, JSON mode)
• Would exceed the daily budget

Cost Tracking Fields

Plan execution metadata includes:

Field	Type	Description
total_tokens	int	Total tokens consumed (input + output)
input_tokens	int	Input/prompt tokens
output_tokens	int	Output/completion tokens
total_cost	float	Estimated cost in USD
budget_remaining	float | None	Remaining plan budget (None if unlimited)
provider_costs	dict[str, float]	Per-provider cost breakdown
budget_exhaustion_events	list	Audit log of budget limit events

Viewing Costs

Use agents plan status to see cost data for a plan:

agents plan status <plan_id>

Cost data appears under the cost key in the output.

Per-Provider Cost Table

Default token cost estimates are provided for offline reporting. Models not in the table use a conservative default estimate.

Supported Providers

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo
• Anthropic: claude-sonnet-4-20250514, claude-3-5-haiku-20241022, claude-opus-4-20250514
• Google: gemini-2.0-flash, gemini-1.5-pro
• Groq: llama-3.1-70b-versatile
• Together: meta-llama/Llama-3.1-70B-Instruct-Turbo
• Cohere: command-r-plus
• Mock: mock-gpt (zero cost)

Budget Exhaustion Events

When a budget limit is reached, an exhaustion event is persisted to the plan's cost metadata with:

• Timestamp
• Budget type (plan or daily)
• Limit amount
• Used amount
• Provider and model that triggered it

These events are retained for auditability and appear in plan status output.

Examples

Set a per-plan budget

export CLEVERAGENTS_BUDGET_PER_PLAN=5.00

Set a daily budget

export CLEVERAGENTS_BUDGET_PER_DAY=50.00

Configure fallback providers

export CLEVERAGENTS_FALLBACK_PROVIDERS='["anthropic", "openai", "groq"]'