Quickstart

Install AgentKavach and start enforcing budgets in under 2 minutes.

Install #

AgentKavach is available on PyPI. Install it with pip:

bash

pip install agentkavach

Get Your API Key #

Sign in to the AgentKavach dashboard and navigate to Keys. Create a key — it is returned once at creation, prefixed with the environment it was minted in (ak_prod_, ak_dev_, or ak_local_). Pass it directly to the constructor or set it in the environment:

bash

export AGENTKAVACH_API_KEY=ak_prod_...

ℹ️ API key vs LLM key

The api_key parameter is your AgentKavach key (ak_{env}_...). llm_key is your provider key (OpenAI, Anthropic, Google, or Mistral). The SDK uses the env tag in the key prefix to route ingest traffic to the matching backend automatically.

ℹ️ Passthrough mode

If api_key is empty or invalid, AgentKavach operates in passthrough mode — LLM calls go directly to the provider with zero overhead. No pre-flight checks, no post-flight recording, no telemetry, no budget enforcement. The request and response are untouched.

Your First Protected Call #

Here is a complete working example that wraps an OpenAI call with a $50/day budget:

python

from agentkavach import AgentKavach, Budget

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

guard = AgentKavach(
    provider="openai",
    api_key="ak_prod_...",               # your AgentKavach key (NOT the LLM key)
    llm_key="sk-...",               # your OpenAI API 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}")

ℹ️ Near-zero latency

Budget checks run in-memory (~0.1ms). No network calls, no added latency.

⚠️ Prompt logging (opt-in)

By default, AgentKavach does not capture or store prompt text. To enable prompt logging for debugging and audit, set save_prompts=True in the constructor. When disabled, the dashboard shows Prompt logging disabled in the events table.

What Just Happened? #

When you call guard.create(), the SDK executes a precise sequence:

Pre-flight budget check — the engine verifies the remaining budget can cover the estimated cost. If not, BudgetExceededError is raised before the LLM call is made.
LLM call — the request is forwarded to the provider (OpenAI, Anthropic, Google, or Mistral) using your llm_key.
Post-flight cost tracking — actual token usage is recorded and the budget is decremented in memory.
Telemetry export — if an API key is configured, usage data is sent to the AgentKavach backend via OpenTelemetry for dashboard visibility.

Next Steps #

Budgets — daily, monthly, total, and shared budget types
Alerts — Slack, email, PagerDuty, and webhook notifications
Guardrails — token limits, call caps, runtime limits, and loop detection
Providers — OpenAI, Anthropic, Google, and Mistral integration guides