YAML Configuration

Manage multiple agents, budgets, alert channels, and shared budgets from a single agentkavach.yaml configuration file. This is the recommended approach for production deployments with many agents.

Full Example #

A complete agentkavach.yaml showing all available options:

yaml

# agentkavach.yaml — full configuration reference

# ── Channel Definitions ──────────────────────────────────────────────
# Reusable channel definitions referenced by name in agent configs.
channels:
  team-email:
    type: email
    to: platform-team@example.com
    api_key: ${RESEND_API_KEY}    # env var interpolation

  oncall-email:
    type: email
    to: oncall@example.com

  alerts-slack:
    type: slack
    webhook_url: ${AGENTKAVACH_SLACK_WEBHOOK_URL}

  ops-pagerduty:
    type: pagerduty
    routing_key: ${AGENTKAVACH_PAGERDUTY_ROUTING_KEY}

  metrics-webhook:
    type: webhook
    url: https://api.example.com/agentkavach-alerts
    secret: ${AGENTKAVACH_WEBHOOK_SECRET}

# ── Defaults ─────────────────────────────────────────────────────────
# Applied to all agents unless overridden.
defaults:
  api_key: ${AGENTKAVACH_API_KEY}
  budget:
    daily: 10.00
    monthly: 200.00
  guardrails:
    max_tokens_per_run: 100000
    max_calls_per_run: 500
    max_runtime_seconds: 600
    detect_loops: true
    loop_threshold: 3
  alerts:
    - channel: team-email
      threshold: 0.50
    - channel: alerts-slack
      threshold: 0.70
    - channel: kill
      threshold: 1.0

# ── Agents ───────────────────────────────────────────────────────────
# Each agent inherits from defaults and can override any setting.
agents:
  research-bot:
    budget:
      daily: 25.00
      monthly: 500.00
    save_prompts: true       # Store prompts in telemetry
    fail_on_error: false     # Fail-open (default)
    guardrails:
      max_tokens_per_run: 200000
      max_runtime_seconds: 1200
    alerts:
      - channel: team-email
        threshold: 0.50
      - channel: alerts-slack
        threshold: 0.70
      - channel: oncall-email
        threshold: 0.80
      - channel: alerts-slack
        threshold: 0.80
      - channel: ops-pagerduty
        threshold: 0.95
      - channel: kill
        threshold: 1.0

  summarizer:
    budget:
      daily: 5.00
    guardrails:
      max_tokens_per_run: 50000
      max_calls_per_run: 100
    alerts:
      - channel: alerts-slack
        threshold: 0.80
      - channel: kill
        threshold: 1.0

  code-reviewer:
    budget:
      daily: 15.00
      monthly: 300.00
      total: 5000.00
    guardrails:
      detect_loops: true
      loop_threshold: 2
    alerts:
      - channel: team-email
        threshold: 0.60
      - channel: metrics-webhook
        threshold: 0.80
      - channel: kill
        threshold: 1.0

  cheap-classifier:
    # Override defaults with minimal budget, no guardrails
    budget:
      daily: 1.00
    guardrails:
      max_tokens_per_run: null
      max_calls_per_run: null
      detect_loops: false
    alerts:
      - channel: kill
        threshold: 1.0

# ── Org Budget ────────────────────────────────────────────────────────
# A single budget that applies across ALL agents in the organization.
# When the org limit is hit, all agents are blocked.
org_budget:
  limit: 50.00
  period: daily              # daily, monthly, or total

# ── Shared Budgets ───────────────────────────────────────────────────
# Pool a single budget across a subset of agents.
shared_budgets:
  analytics-team:
    budget:
      daily: 50.00
      monthly: 1000.00
    agents:
      - research-bot
      - summarizer
    alerts:
      - channel: team-email
        threshold: 0.70
      - channel: ops-pagerduty
        threshold: 0.95
      - channel: kill
        threshold: 1.0

Loading from YAML #

Load all agents

Load every agent defined in the config file. Returns a dictionary keyed by agent name:

python

from agentkavach import AgentKavach

def emergency_stop(agent_name, spent, budget):
    print(f"KILLED: {agent_name} at {spent:.2f}/{budget:.2f}")

# Load all agents from the YAML file
clients = AgentKavach.from_yaml("agentkavach.yaml", on_kill=emergency_stop)

# Access individual agents
research = clients["research-bot"]
summarizer = clients["summarizer"]

# Use them like normal AgentKavach instances
response = research.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze this paper..."}],
)

Load a single agent

Load only a specific agent by name. This is more efficient when you only need one agent from a large config file:

python

from agentkavach import AgentKavach

guard = AgentKavach.from_yaml(
    "agentkavach.yaml",
    agent="research-bot",
    on_kill=emergency_stop,
)

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

Schema Reference #

Top-level keys

Parameter	Type	Required	Default	Description
`channels`	`map`	No	—	Named channel definitions. Each key is a channel name, value is the channel config.
`defaults`	`map`	No	—	Default settings applied to all agents. Can include api_key, budget, guardrails, and alerts.
`agents`	`map`	Yes	—	Agent definitions. Each key is the agent name, value is the agent config. Inherits from defaults.
`org_budget`	`map`	No	—	Organization-wide budget applied to ALL agents. Contains limit (float) and period (daily/monthly/total). Most restrictive wins when combined with per-agent budgets.
`shared_budgets`	`map`	No	—	Shared budget pools for subsets of agents. Each key is the pool name, value includes budget, agents list, and alerts.

Channel definition

Parameter	Type	Required	Default	Description
`type`	`str`	Yes	—	Channel type: email, slack, pagerduty, or webhook.
`to`	`str`	No	—	Email recipient (email channels only).
`api_key`	`str`	No	—	API key for the channel provider (email only).
`webhook_url`	`str`	No	—	Webhook URL (slack channels only).
`routing_key`	`str`	No	—	Routing key (pagerduty channels only).
`url`	`str`	No	—	Target URL (webhook channels only).
`secret`	`str`	No	—	HMAC signing secret (webhook channels only).
`template`	`str`	No	—	Custom message template with variable interpolation.

Budget definition

Parameter	Type	Required	Default	Description
`daily`	`float`	No	—	Daily budget limit in USD. Resets at midnight.
`monthly`	`float`	No	—	Monthly budget limit in USD. Resets on the 1st of each month.
`total`	`float`	No	—	Lifetime total budget limit in USD. Never resets.

Guardrails definition

Parameter	Type	Required	Default	Description
`max_tokens_per_run`	`int \| null`	No	—	Maximum total tokens per run. null disables.
`max_calls_per_run`	`int \| null`	No	—	Maximum LLM calls per run. null disables.
`max_runtime_seconds`	`float \| null`	No	—	Maximum wall-clock seconds per run. null disables.
`detect_loops`	`bool`	No	false	Enable loop detection.
`loop_threshold`	`int`	No	3	Repetitions before loop detection fires.

Alert definition

Parameter	Type	Required	Default	Description
`channel`	`str`	Yes	—	Reference to a named channel (from the channels section) or the literal "kill".
`threshold`	`float`	Yes	—	Budget percentage (0.0 to 1.0) to trigger the alert.

Environment Variable Interpolation #

Use ${VAR_NAME} syntax anywhere in the YAML to reference environment variables. This keeps secrets out of your config file:

yaml

channels:
  team-email:
    type: email
    api_key: ${RESEND_API_KEY}        # resolved from env at load time

defaults:
  api_key: ${AGENTKAVACH_API_KEY}     # resolved from env at load time

⚠️ Missing env vars

If a referenced environment variable is not set, AgentKavach will raise a ConfigurationError at load time with the name of the missing variable.

Validation #

AgentKavach validates the entire YAML config at load time and raises ConfigurationError for any issues. The following checks are performed:

Channel references — every channel referenced in an alert must be defined in the channels section (or be the literal "kill").
Required fields — each channel type must have its required fields (e.g., to for email, webhook_url for slack).
Threshold range — all thresholds must be between 0.0 and 1.0 inclusive.
Budget values — all budget amounts must be positive numbers.
Agent names — agent names must be non-empty strings with no special characters.
Environment variables — all ${...} references must resolve to a set environment variable.
Shared budget agents — every agent listed in a shared budget must be defined in the agents section.
URL format — Slack webhook URLs must start with https://.
Guardrail values — numeric guardrail values must be positive when set.

python

from agentkavach import AgentKavach
from agentkavach.exceptions import ConfigurationError

try:
    clients = AgentKavach.from_yaml("agentkavach.yaml")
except ConfigurationError as e:
    print(f"Invalid config: {e}")
    # e.g., "Unknown channel 'slack-typo' in agent 'research-bot' alerts"
    # e.g., "Missing env var: RESEND_API_KEY"
    # e.g., "Threshold 1.5 out of range [0.0, 1.0] for agent 'summarizer'"