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: Resend key. Omit to use backend dispatch.
`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>.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.