Control

Policies

Policies are the rules that govern how the Niitaka policy engine intervenes in agent runs. They let you define cost and step budgets, automatic retry strategies, and model fallbacks — without touching your agent code.

Each policy is evaluated in real time on every incoming event. When a condition is met, the configured action executes and a signal is emitted to the feed.

Policy types

cost_limitCap cumulative LLM spend per session.warn / abort
step_limitCap the number of steps (events) per session.warn / abort
retryAuto-retry the last step on error.retry with back-off
fallbackSwitch to a backup model when retries fail.swap model

cost_limit

Tracks cumulative LLM spend for the session and fires when total_cost crosses the threshold. Two tiers are standard: a warn action at a lower threshold (emits a signal, continues running) and an abort action at a higher threshold (stops the session).

FieldTypeDescription
condition.cost_exceededfloatUSD threshold that triggers this rule.
action.typestring"warn" — emit signal and continue. "abort" — stop the session.
priorityintHigher priority wins when multiple rules match the same event.

step_limit

Counts the number of steps (events) in the session and fires when the count reaches the threshold. Same two-tier warn/abort pattern as cost_limit.

FieldTypeDescription
condition.steps_exceededintStep count threshold.
action.typestring"warn" or "abort".
priorityintHigher priority wins.

retry

Automatically retries the last event when the agent reports an error. Supports exponential, linear, and constant back-off algorithms.

FieldTypeDescription
action.max_retriesintMaximum number of retry attempts.
action.backoffstring"exponential" | "linear" | "constant".
action.backoff_secondsfloatBase delay in seconds. Exponential: delay × 2^attempt. Linear: delay × attempt. Constant: fixed delay.
action.on_errorslistOptional list of error type strings to match. Empty = match all errors.

fallback

Switches to a different model when retries are exhausted or a specific error occurs. Useful for ensuring continuity when a primary provider is unavailable.

FieldTypeDescription
action.fallback_modelstringModel identifier to switch to (e.g. "gpt-4o-mini").
action.on_errorslistOptional error type filter. Empty = match all errors.

UI policies vs file-based policies

Policies can be created in two ways:

UI (source: ui)Created and edited via the Policies dashboard. Stored in the database. Editable at any time. Changes take effect on the next event.
File (source: file)Pushed from a YAML file via the SDK CLI or loaded at runtime via niitaka.configure(policy_file=...). Shown as read-only in the UI — you can view and delete them but not edit inline. The source of truth is your version-controlled file.
Tip:For production agents, prefer file-based policies. They live in your repository, are reviewed in pull requests, and roll back with your code. UI policies are convenient for experimentation but harder to audit.

Policy YAML format

yaml
version: "1"

policies:
  # Warn at $0.10, hard-abort at $0.25
  - agent_id: report-summariser
    type: cost_limit
    priority: 5
    condition:
      cost_exceeded: 0.10
    action:
      type: warn

  - agent_id: report-summariser
    type: cost_limit
    priority: 10
    condition:
      cost_exceeded: 0.25
    action:
      type: abort

  # Warn at 30 steps, abort at 50
  - agent_id: report-summariser
    type: step_limit
    priority: 5
    condition:
      steps_exceeded: 30
    action:
      type: warn

  - agent_id: report-summariser
    type: step_limit
    priority: 10
    condition:
      steps_exceeded: 50
    action:
      type: abort

  # Retry up to 3 times with exponential back-off
  - agent_id: report-summariser
    type: retry
    priority: 3
    condition:
      on_error: true
    action:
      max_retries: 3
      backoff: exponential
      backoff_seconds: 2.0

  # Fall back to a cheaper model after retries fail
  - agent_id: report-summariser
    type: fallback
    priority: 1
    condition:
      on_error: true
    action:
      fallback_model: gpt-4o-mini
bash
# Push policy file to the backend (replaces any existing UI-defined policies)
python -m sdk.cli push agents/report-summariser/policies.yaml

# Or configure the SDK to load from file at runtime
niitaka.configure(policy_file="policies.yaml")

Priority and conflict resolution

When multiple policies match the same event, the one with the highest priority value wins. Typical convention:

  • priority 10 — hard abort (highest urgency)
  • priority 5–8 — warn-level guardrails
  • priority 1–4 — soft actions (retry, fallback)

Audit log

Every policy change is recorded in the Audit Log tab on the Policies page. Each entry shows the action taken (create, delete, replace), the before and after state as expandable JSON, the source (UI or file), and the timestamp.

Note:The audit log is append-only and cannot be edited. It provides a complete history of every guardrail change for compliance and incident review.

Next steps

  • Policy Evaluation — understand how the engine evaluates policies on each event.
  • Signals & Alerts — see the signals your policies emit and configure external notifications.

Previous

Signals & Alerts

Next

Policy Evaluation

Was this page helpful?
Need help? Contact SupportQuestions? Contact SalesLLM? Read llms.txt