AgentKavach

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 before you leave the page.
  • 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 right away rather than failing quietly later on.
  • An expired or revoked key is handled gently. Your calls keep running and the SDK simply stops exporting telemetry, so a key that lapses in production never takes your application down with it.

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}")
  • AgentKavach checks the budget in memory before every call, so the guardrail stays out of the way and your code runs just as it did before.
  • 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:

  1. Preflight. Before anything leaves your machine, the engine estimates what the request will cost and compares it to what is left in the budget. If the budget cannot cover it, the SDK raises BudgetExceededError and the call never goes out.
  2. Provider call. When there is room, the request travels on to your provider using your llm_key.
  3. Tracking. Once the response comes back, the SDK records the actual token usage and subtracts it from the budget it holds in memory.
  4. Telemetry. The event is exported to the backend over OpenTelemetry and appears in your dashboard moments later.

Next steps #

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

  • Budgets covers the daily, monthly, total, and shared limit types.
  • Alerts explains how to wire up Slack, email, PagerDuty, and webhook notifications.
  • Guardrails describes the token, call, runtime, and loop protections.
  • Providers walks through using OpenAI, Anthropic, Google, and Mistral interchangeably.