YAML configuration

Define every agent in one file and load them with AgentKavach.from_yaml(). Use YAML when you run a fleet of agents that share alert channels or a budget pool.

Optional

YAML is one of three ways to configure agents. You can configure each agent in code (see Quickstart) or manage budgets and alerts from the dashboard.

Example #

yaml

# agentkavach.yaml

channels:
  team-slack:
    type: slack
    webhook_url: ${AGENTKAVACH_SLACK_WEBHOOK_URL}
  oncall-pd:
    type: pagerduty
    routing_key: ${AGENTKAVACH_PAGERDUTY_ROUTING_KEY}

org_budget:
  limit: 1000
  period: daily

defaults:
  provider: openai
  budget:
    type: daily
    limit: 50
  alerts:
    - threshold: 0.80
      channels: [team-slack]
    - threshold: 1.0
      channels: [team-slack, kill]

agents:
  research-bot:
    budget:
      type: daily
      limit: 100
    alerts:
      - threshold: 0.80
        channels: [team-slack]
      - threshold: 0.95
        channels: [oncall-pd]
      - threshold: 1.0
        channels: [oncall-pd, kill]

  support-agent:
    provider: anthropic
    budget: default          # inherit defaults.budget

Loading

python

from agentkavach import AgentKavach

# Load every agent
clients = AgentKavach.from_yaml("agentkavach.yaml", on_kill=lambda: None)
research = clients["research-bot"]

# Load a single agent
support = AgentKavach.from_yaml("agentkavach.yaml", agent="support-agent")

Schema #

Top-level keys

Parameter	Type	Required	Default	Description
`channels`	`map`	No	—	Named alert channel definitions. Referenced by name in alerts. The built-in 'kill' is always available.
`org_budget`	`map`	No	—	Single org-wide budget applied to every agent loaded from this file (limit, period).
`defaults`	`map`	No	—	Default settings merged into every agent.
`agents`	`map`	Yes	—	Agent definitions, keyed by agent name.

channels.<name>

Parameter	Type	Required	Default	Description
`type`	`string`	Yes	—	One of "slack", "email", "pagerduty", "webhook".
`webhook_url`	`string`	No	—	Slack only.
`to`	`string`	No	—	Email recipient.
`api_key`	`string`	No	—	Email: legacy Resend key. Omit it — the cloud delivers email for you.
`routing_key`	`string`	No	—	PagerDuty Events API v2 routing key.
`url`	`string`	No	—	Webhook target URL.
`secret`	`string`	No	—	Webhook HMAC-SHA256 signing secret.

agents.<name>.budget

Parameter	Type	Required	Default	Description
`type`	`string`	No	"daily"	"daily", "monthly", or "total".
`limit`	`float`	No	100.0	Limit in USD. Must be > 0.

The literal budget: default tells the loader to inherit defaults.budget verbatim.

agents.<name>.guardrails

Per-run guardrails, identical to the inline constructor arguments. Each is optional; an unknown key raises ValueError so a typo can never silently disable a limit.

Parameter	Type	Required	Default	Description
`max_tokens_per_run`	`int`	No	—	Raise TokenLimitError once the run's total tokens reach this cap.
`max_calls_per_run`	`int`	No	—	Raise CallLimitError once the run reaches this many LLM calls.
`max_runtime_seconds`	`float`	No	—	Raise RuntimeLimitError once the run's wall-clock reaches this duration.
`detect_loops`	`bool`	No	false	Raise LoopDetectedError when a repeating call pattern is detected.
`loop_threshold`	`int`	No	3	Number of repetitions that counts as a loop (with detect_loops).

yaml

agents:
  research-bot:
    budget:
      type: daily
      limit: 50
    guardrails:
      max_tokens_per_run: 200000
      max_runtime_seconds: 600
      max_calls_per_run: 100
      detect_loops: true
      loop_threshold: 3

agents.<name>.alerts

A list of rules.

Parameter	Type	Required	Default	Description
`threshold`	`float`	Yes	—	Trigger ratio in (0.0, 1.0]. Alias: "at".
`channels`	`list[string]`	No	["email"]	Channel names from the channels: section, plus the built-in 'kill'. Unknown names raise ValueError.
`action`	`string`	No	—	Legacy convenience: "kill" appends "kill" to channels.

Other agent fields

Parameter	Type	Required	Default	Description
`provider`	`string`	No	"openai"	"openai", "anthropic", "google", or "mistral".
`save_prompts`	`bool`	No	false	Send prompt text to telemetry. Off by default.
`fail_on_error`	`bool`	No	false	When true, any internal SDK error invokes on_kill and re-raises instead of failing open.

org_budget

Parameter	Type	Required	Default	Description
`limit`	`float`	Yes	—	Org-wide limit in USD.
`period`	`string`	No	"daily"	"daily", "monthly", or "total".

Environment variables #

AgentKavach does not expand ${VAR} inside YAML values, and it never reads credentials from the environment on your behalf. Use shell expansion with envsubst or a templating tool to fill the values in, or pass the credential explicitly to the constructor.

Validation #

The loader raises plain Python exceptions when something is wrong.

ValueError for unknown channel types, undefined channel references in alerts, unknown budget types, or thresholds outside (0, 1.0].
KeyError when from_yaml(..., agent="name") is called with an agent that is not in the file.
FileNotFoundError or yaml.YAMLError for missing files or malformed YAML.