YAML Configuration

Define multiple agents in one file and load them with AgentKavach.from_yaml(). Useful 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 also 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}

shared_budgets:
  engineering-pool:
    limit: 500
    period: daily

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

  scratch:
    budget:
      shared: engineering-pool   # draw from shared pool

Loading

python

from agentkavach import AgentKavach

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

# 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 (plus the built-in 'kill').
`shared_budgets`	`map`	No	—	Named pooled budgets. Agents reference one by name via budget.shared.
`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.
`shared`	`string`	No	—	Name of a shared_budgets entry. When set, type/limit are ignored and the agent draws from the pool.

The literal value 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 defined in 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.

shared_budgets.<name>

Parameter	Type	Required	Default	Description
`limit`	`float`	Yes	—	Pool limit in USD.
`period`	`string`	No	"daily"	"daily", "monthly", or "total".
`agents`	`list[string]`	No	—	Documentation only — the loader records but does not enforce this list.

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 perform ${VAR} expansion inside YAML values itself. Use standard shell expansion (envsubst), a templating layer of your choice, or set the relevant channel environment variables and omit the credential from the YAML — the SDK falls back to environment variables when channel-level credentials are absent.

Validation #

The loader raises plain Python exceptions when it encounters problems:

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 / yaml.YAMLError for missing files or malformed YAML.