Guardrails

Guardrails prevent runaway agents by enforcing per-run limits, session budgets, daemon budgets, and autonomous budgets. All limits are enforced automatically — agents stop when a limit is hit and warn at 80% consumption.

Quick Example

guardrails:
  max_tokens_per_run: 50000
  max_tool_calls: 20
  timeout_seconds: 300
  session_token_budget: 200000

Per-Run Limits

These limits apply to each individual agent run (a single invocation or trigger execution).

Field	Type	Default	Description
`max_tokens_per_run`	`int`	`50000`	Maximum output tokens consumed per agent run
`max_tool_calls`	`int`	`20`	Maximum tool invocations per run
`timeout_seconds`	`int`	`300`	Wall-clock timeout per run (seconds)
`max_request_limit`	`int \| null`	auto	Maximum LLM API round-trips per run. Auto-derived as `max(max_tool_calls + 10, 30)` when not set
`input_tokens_limit`	`int \| null`	`null`	Per-request input token limit
`total_tokens_limit`	`int \| null`	`null`	Per-request combined input+output token limit

Session Budgets

guardrails:
  session_token_budget: 500000

session_token_budget tracks cumulative token usage across interactive REPL turns (-i mode). The agent warns at 80% consumption and stops accepting new prompts at 100%.

This is useful for long-running interactive sessions where you want to cap total spend.

Daemon Budgets

Daemon-mode agents (initrunner daemon) can have lifetime and daily budgets:

Field	Type	Default	Description
`daemon_token_budget`	`int \| null`	`null`	Lifetime token budget for the daemon process
`daemon_daily_token_budget`	`int \| null`	`null`	Daily token budget — resets at UTC midnight

guardrails:
  daemon_token_budget: 1000000
  daemon_daily_token_budget: 100000

When a daemon budget is exhausted, triggers are skipped until the budget resets (daily) or the daemon is restarted (lifetime).

Autonomous Limits

These fields control resource usage for autonomous mode runs:

Field	Type	Default	Description
`max_iterations`	`int`	`10`	Maximum plan-execute-adapt cycles
`autonomous_token_budget`	`int \| null`	`null`	Token budget for the autonomous run
`autonomous_timeout_seconds`	`int \| null`	`null`	Wall-clock timeout for the entire autonomous run

guardrails:
  max_iterations: 10
  autonomous_token_budget: 50000
  autonomous_timeout_seconds: 600

When any autonomous limit is hit, the agent stops and reports its progress via finish_task.

Enforcement Behavior

Each limit type has specific enforcement behavior:

Limit	What Happens
`max_tokens_per_run`	PydanticAI raises `UsageLimitExceeded` — the run stops immediately
`max_tool_calls`	PydanticAI raises `UsageLimitExceeded` — the run stops immediately
`timeout_seconds`	Python raises `TimeoutError` — the run is cancelled
`max_request_limit`	PydanticAI raises `UsageLimitExceeded` — no more API round-trips
`input_tokens_limit`	PydanticAI raises `UsageLimitExceeded` on the next request
`total_tokens_limit`	PydanticAI raises `UsageLimitExceeded` on the next request
`session_token_budget`	Warns at 80%, stops accepting prompts at 100%
`daemon_token_budget`	Triggers are skipped when exhausted
`daemon_daily_token_budget`	Triggers are skipped until UTC midnight reset
`max_iterations`	Autonomous loop terminates, agent reports progress
`autonomous_token_budget`	Autonomous loop terminates, agent reports progress
`autonomous_timeout_seconds`	Autonomous loop terminates, agent reports progress

The 80% warning applies to session_token_budget, daemon_token_budget, and daemon_daily_token_budget. When 80% of the budget is consumed, a warning is logged so operators can take action before the hard stop.

CLI Overrides

# Override max iterations for autonomous mode
initrunner run role.yaml -a --max-iterations 5

The --max-iterations N flag overrides the max_iterations value from the YAML file for that run.

Full Example

A daemon role with daily budgets and autonomous limits:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: monitor-agent
  description: Monitors infrastructure and auto-remediates issues
spec:
  role: |
    You are an infrastructure monitor. Check system health when triggered,
    diagnose issues, and apply standard remediations.
  model:
    provider: openai
    name: gpt-4o-mini
    temperature: 0.0
  tools:
    - type: shell
      allowed_commands: [curl, systemctl, journalctl]
      require_confirmation: false
      timeout_seconds: 30
  triggers:
    - type: cron
      schedule: "*/5 * * * *"
      prompt: "Run a health check on all services."
      autonomous: true
  autonomy:
    max_plan_steps: 8
    max_history_messages: 20
    iteration_delay_seconds: 2
  guardrails:
    # Per-run limits
    max_tokens_per_run: 15000
    max_tool_calls: 10
    timeout_seconds: 120
    # Daemon budgets
    daemon_token_budget: 5000000
    daemon_daily_token_budget: 500000
    # Autonomous limits
    max_iterations: 5
    autonomous_token_budget: 30000
    autonomous_timeout_seconds: 300

On this page