SDK Reference

Reference material for the SDK's exception types and its behavioral options. For the limits that terminate an agent, see Budgets and Guardrails.

Exceptions #

AgentKavach raises a small, typed set of exceptions when an agent is terminated. A cost budget raises BudgetExceededError. The guardrail and per-instance limits raise a subclass of GuardrailError, so a single except GuardrailError clause catches all of them, or you can catch a specific type.

Exception	Base class	Raised when
`BudgetExceededError`	`Exception`	A cost budget (daily, monthly, total, or org) is reached.
`TokenLimitError`	`GuardrailError`	`max_tokens_per_run` is reached.
`RuntimeLimitError`	`GuardrailError`	`max_runtime_seconds` is reached.
`CallLimitError`	`GuardrailError`	`max_calls_per_run` is reached.
`LoopDetectedError`	`GuardrailError`	A repeating call pattern trips loop detection.

python

from agentkavach.exceptions import (
    BudgetExceededError,
    GuardrailError,
    TokenLimitError,
)

try:
    response = guard.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except TokenLimitError as e:
    print(f"Tokens: {e.spent}/{e.limit}")
except GuardrailError as e:
    print(f"Guardrail tripped: {e}")
except BudgetExceededError as e:
    print(f"Budget reached: {e.spent}/{e.limit}")

ℹ️ Only termination errors propagate

These exceptions are the only ones AgentKavach raises on purpose. All other internal errors are caught and logged so they never block an LLM call, unless you opt into fail_on_error below.

fail_on_error #

By default AgentKavach is fail-open: an internal SDK error (network, parsing, and similar) never blocks your LLM call. Set fail_on_error=True to raise on those internal errors instead, trading availability for stricter enforcement.

python

guard = AgentKavach(
    provider="openai",
    api_key="ak_prod_...",
    llm_key="sk-...",
    budget=Budget.daily(50),
    fail_on_error=True,
)

⚠️ Changes failure semantics

With fail_on_error=True, an internal AgentKavach error raises and your call does not complete. Use it only when you would rather stop than risk an unmetered call.

save_prompts #

Prompt text is not stored by default. Set save_prompts=True to record prompt text in the dashboard events table for debugging. While it is off, the dashboard shows that prompt logging is disabled.

python

guard = AgentKavach(
    provider="openai",
    api_key="ak_prod_...",
    llm_key="sk-...",
    budget=Budget.daily(50),
    save_prompts=True,
)

ℹ️ Privacy

Prompt text is never stored unless you explicitly enable it. See the privacy policy for retention details.