AI Agents

Guardrails

Guardrails are safety limits that control what AI agents can and cannot do. Configure them globally or per-agent to match your risk tolerance.

Available Guardrails

approval_mode

enum

default: approve

Controls how agent actions are handled. "auto" lets the trust tier decide, "approve" requires manual approval, "notify" auto-executes but notifies you, "disabled" turns the agent off.

Options: auto, approve, notify, disabled

confidence_threshold

float

default: 0.7

Minimum confidence score required for an agent to act. Actions below this threshold are escalated for review.

Options: 0.0 - 1.0

max_actions_per_hour

integer

default: 50

Rate limit on how many actions an agent can execute per hour. Prevents runaway automation.

Options: 1 - 1000

max_financial_impact

USD

default: $1,000

Maximum financial impact of a single agent action. Actions exceeding this are held for approval regardless of trust tier.

Options: $1 - $100,000

allowed_action_types

array

default: [] (all allowed)

Whitelist of action types the agent can perform. Empty means all actions are allowed.

Options: string[]

blocked_action_types

array

default: [] (none blocked)

Blacklist of action types the agent cannot perform. Takes priority over allowed_action_types.

Options: string[]

custom_rules

JSON

default: {}

Advanced rules engine for complex conditions. Supports conditional logic based on product category, time of day, inventory levels, etc.

Options: object

Configuration Methods

Via Dashboard

// Configure guardrails via the dashboard:
// Navigate to: Settings → Agents → Select Agent → Guardrails
//
// The dashboard provides a visual editor for all guardrail
// settings with real-time validation and preview.

Via API

// Configure guardrails via API
const response = await fetch('/api/v1/agents/pricing_agent/guardrails', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-CI-Api-Key': 'your_api_key',
    'X-CI-Merchant-Id': 'merch_xyz789'
  },
  body: JSON.stringify({
    approval_mode: 'auto',
    confidence_threshold: 0.8,
    max_actions_per_hour: 30,
    max_financial_impact: 500,
    allowed_action_types: ['price_adjustment', 'deal_creation'],
    blocked_action_types: ['product_delete'],
    custom_rules: {
      max_discount_pct: 25,
      min_margin_pct: 10,
      blackout_hours: [0, 1, 2, 3, 4, 5]
    }
  })
});

Via Messaging (/policy command)

// Configure guardrails via messaging (/policy command)
/policy set pricing_agent.approval_mode auto
// ✅ pricing_agent approval_mode set to auto

/policy set pricing_agent.confidence_threshold 0.85
// ✅ pricing_agent confidence_threshold set to 0.85

/policy set pricing_agent.max_actions_per_hour 25
// ✅ pricing_agent max_actions_per_hour set to 25

/policy
// 📋 Current policies:
// pricing_agent:
//   approval_mode: auto
//   confidence_threshold: 0.85
//   max_actions_per_hour: 25
//   max_financial_impact: $500
//   trust_tier: supervised

Per-Agent vs Global Guardrails

Guardrails can be set at two levels:

Global Guardrails

Apply to all agents by default. Set these as your baseline safety net. Configured in Settings → Agent Policies → Global.

Per-Agent Guardrails

Override global settings for a specific agent. Per-agent settings always take precedence. The more restrictive value wins when comparing global vs per-agent.

Financial Limits by Trust Tier

Guardrails work in conjunction with trust tiers. The trust tier sets baseline financial limits, and guardrails can further restrict (but not expand) those limits.

Tier	Auto-Approve Below	Force Approval Above	Behavior
Probation	$0	$0	All actions need approval
Supervised	$50	$200	Up to $200 with auto-approve threshold
Trusted	$500	$2,000	Up to $2,000 with auto-approve threshold
Autonomous	$5,000	$10,000	Up to $10,000 with auto-approve threshold

Example Configurations

Conservative (Low Risk)

Best for new merchants or high-value products. Maximum human oversight.

{
  "approval_mode": "approve",
  "confidence_threshold": 0.9,
  "max_actions_per_hour": 10,
  "max_financial_impact": 100,
  "allowed_action_types": ["price_adjustment"],
  "blocked_action_types": ["product_delete", "bulk_update"],
  "custom_rules": {
    "max_discount_pct": 10,
    "require_approval_weekends": true
  }
}

Balanced (Recommended)

Good default for most merchants. Trust-tier-driven automation with sensible limits.

{
  "approval_mode": "auto",
  "confidence_threshold": 0.7,
  "max_actions_per_hour": 50,
  "max_financial_impact": 1000,
  "allowed_action_types": [],
  "blocked_action_types": ["product_delete"],
  "custom_rules": {
    "max_discount_pct": 25,
    "min_margin_pct": 10
  }
}

Aggressive (High Autonomy)

For experienced merchants comfortable with AI-driven decisions. Maximize speed and volume.

{
  "approval_mode": "notify",
  "confidence_threshold": 0.5,
  "max_actions_per_hour": 200,
  "max_financial_impact": 5000,
  "allowed_action_types": [],
  "blocked_action_types": [],
  "custom_rules": {
    "max_discount_pct": 50,
    "allow_flash_deals": true
  }
}