Quickstart

Install AgentKavach and put a real budget around your first call in about two minutes.

Install #

Everything ships in one package. Install it with pip and you are ready to wrap your first provider call.

bash

pip install agentkavach

Get your API key #

Three quick steps to a working key:

Sign in to the dashboard and open the Keys page.
Click Create key. The raw key is shown only once, so copy it somewhere safe.
Hand the key to the constructor yourself. The SDK never reads it from the environment, so the cleanest habit is to keep it out of your source and read it at startup.

bash

export AGENTKAVACH_API_KEY=ak_prod_...

A few things worth knowing about the two keys involved:

Your api_key is the AgentKavach key you just created; your llm_key is the provider key you already use for OpenAI, Anthropic, Google, or Mistral.
Every AgentKavach key starts with ak_.
Both keys are required. If either is missing, the constructor raises an error.
If the AgentKavach key is expired or revoked, your LLM calls keep working; the SDK just stops exporting telemetry. A lapsed key never takes down your app.

Your first AgentKavach call #

The example below wraps an ordinary OpenAI call in a hard limit of $50 per day. You write the same code you always would; AgentKavach sits in front of it and keeps the spend in check.

python

from agentkavach import AgentKavach, Budget

def emergency_stop():
    agent.save_checkpoint()
    sys.exit(1)

guard = AgentKavach(
    provider="openai",
    api_key=os.environ["AGENTKAVACH_API_KEY"],   # your AgentKavach key
    llm_key=os.environ["OPENAI_API_KEY"],        # your OpenAI key
    agent_name="research-bot",
    budget=Budget.daily(50),                     # $50/day hard limit
    on_kill=emergency_stop,
)

response = guard.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(f"Spent: ${guard.spent:.4f}, Remaining: ${guard.remaining:.4f}")

The budget check runs in memory on every call, so it adds no latency for OpenAI and Mistral. (Anthropic and Google add one fast token-count request to the provider.)
Prompt text is never stored by default. Set save_prompts=True on the constructor to capture prompts in the dashboard; until you do, the Events table shows that prompt logging is off.

What just happened #

Every call to guard.create() moves through the same four stages, in order:

Check. The SDK compares the spend it has already recorded against the budget. If an earlier call pushed you over the limit, it raises BudgetExceededError now and the call stops. Otherwise the call proceeds.
Provider call. The request goes to your provider with your llm_key. For Anthropic and Google the SDK first makes a fast token-count call to the provider; OpenAI and Mistral are counted locally.
Record. When the response returns, the SDK adds the actual cost to the running total. Cost comes from a built-in price table times the token counts, with no extra network call. The call that crosses the limit still completes and is billed; the next call is the one that is blocked.
Export. The event is sent to the backend over OpenTelemetry and appears on your dashboard moments later.

Next steps #

When you are ready to go further, the rest of the documentation picks up where this leaves off:

Limits & budgets covers cost, token, duration, call-count, and loop limits.
Alerts explains how to wire up Slack, email, PagerDuty, and webhook notifications.
Providers walks through using OpenAI, Anthropic, Google, and Mistral interchangeably.