Shared Budgets

Pool a single budget across multiple agents and providers. Spend from any agent decrements the same pool, with thread-safe enforcement.

Overview #

Shared budgets let you define a single spending pool that multiple agents draw from. This is useful when you have a team-wide or project-wide budget and want to enforce it across all agents regardless of which LLM provider they use.

Full Example #

Here two agents — one using OpenAI and one using Anthropic — share a $500/day budget pool:

python

from agentkavach import AgentKavach, Budget

# Create a shared budget pool
pool = Budget.shared_budget(
    "engineering-pool",
    Budget.daily(500),
)

# OpenAI agent draws from the shared pool
openai_guard = AgentKavach(
    provider="openai",
    api_key="cg_...",
    llm_key="sk-...",
    agent_name="research-bot",
    budget=pool,
)

# Anthropic agent draws from the same pool
anthropic_guard = AgentKavach(
    provider="anthropic",
    api_key="cg_...",
    llm_key="sk-ant-...",
    agent_name="support-agent",
    budget=pool,
)

# Both calls decrement the same $500/day pool
r1 = openai_guard.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze this dataset"}],
)

r2 = anthropic_guard.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Summarize this report"}],
    max_tokens=1024,
)

# Check shared pool state from either guard
print(f"Pool spent: ${openai_guard.spent:.4f}")
print(f"Pool remaining: ${anthropic_guard.remaining:.4f}")

Budget.shared_budget() Parameters #

Parameter	Type	Required	Default	Description
`name`	`str`	Yes	—	Unique name for the shared pool. Used as the key to identify the budget across agents.
`budget`	`Budget`	Yes	—	The underlying budget instance (Budget.daily, Budget.monthly, or Budget.total) that defines the limit and period.

When using YAML configuration, shared budgets accept additional fields:

Parameter	Type	Required	Default	Description
`limit`	`float`	Yes	—	USD limit for the shared pool. Must be > 0.
`period`	`str`	Yes	—	Budget period: "daily", "monthly", or "total".
`agents`	`list[str]`	Yes	—	List of agent names that share this pool. All listed agents must be defined in the agents section.

yaml

# agentkavach.yaml
shared_budgets:
  engineering-pool:
    limit: 500
    period: daily
    agents: [research-bot, support-agent]

Thread Safety #

Shared budgets are fully thread-safe. All mutable state is protected behind a threading.Lock, so you can safely use a shared pool from multiple threads or async tasks without risk of race conditions or double-spending.

ℹ️ Thread-safe by default

You do not need to add your own locking. The SDK handles concurrency internally for all budget types, including shared budgets.

Shared Budget Key Format #

Internally, shared budgets are keyed by the name you provide. Two agents sharing the same pool must reference the exact same Budget.shared_budget() instance (or the same YAML pool name). The key format is:

text

shared:<name>:<period>

For example, a daily shared budget named engineering-pool has the internal key shared:engineering-pool:daily. This key is used for telemetry grouping and dashboard display.

⚠️ Same instance required

If you create two separate Budget.shared_budget() calls with the same name, they will be two independent pools. Always assign the shared budget to a variable and pass it to all agents that should share it.

Org Budgets vs. Shared Budgets #

AgentKavach offers two kinds of pooled budgets. Choose based on your needs:

Feature	Org Budget	Shared Budget
Scope	All agents in the org (automatic)	Only agents you explicitly list
Setup	`Budget.org_budget(50)`	`Budget.shared_budget("name", ...)`
YAML key	`org_budget`	`shared_budgets.<name>`
Dashboard	Settings → Organization Budget	Per-agent budget config
API	`/v1/org/budgets`	Configured per agent
Server enforcement	Ingest returns 429 when org limit hit	SDK-side only (in-memory)
Best for	Company-wide spending caps	Team or project-level pools

ℹ️ Use both together

Org budgets and shared budgets can be used together. An agent can have its own individual budget, belong to a shared budget pool, and be covered by the org budget — all at the same time. The most restrictive limit always wins.

Org Budget Quick Start #

Set up an organization-wide budget that covers all agents:

python

from agentkavach import AgentKavach, Budget

# Org budget: $100/day across all agents
org = Budget.org_budget(limit=100, period="daily")

guard = AgentKavach(
    provider="openai",
    api_key="cg_...",
    llm_key="sk-...",
    agent_name="my-agent",
    budget=Budget.daily(25),     # individual limit
    org_budget=org,              # org-wide limit
)

Or via YAML configuration:

yaml

# agentkavach.yaml
org_budget:
  limit: 100.00
  period: daily

agents:
  my-agent:
    budget:
      daily: 25.00

Or via the dashboard API:

bash

curl -X POST http://localhost:8000/v1/org/budgets \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"budget_type": "cost", "period": "daily", "limit_value": 100.0}'