DocumentationPromoting & Demoting Agents

Promoting & Demoting Agents

4 minLast updated: 2026-03-31

Promotion Requirements

To promote an agent to a higher trust level, it must meet minimum thresholds:

  • L0 → L1: No requirements (immediate)
  • L1 → L2: 7 days active, 100+ interactions, 0 critical incidents
  • L2 → L3: 14 days active, 500+ interactions, max 2 high-severity incidents
  • L3 → L4: 30 days active, 1,000+ interactions, max 1 incident of any severity, owner approval required
POST /api/v1/agents/:id/trust/promote
{
  "targetLevel": 3
}

Auto-Demotion Triggers

Agents are automatically demoted when security issues are detected:

  • Critical prompt injection detected: Immediate demotion to L0 with 24-hour cooldown
  • Kill switch activated: Immediate demotion to L0 with 24-hour cooldown
  • Circuit breaker trips twice: Demoted one level
  • 3+ high-severity incidents: Demoted one level

All demotions are logged in the trust history with the reason and triggering event.

Kill Switch

Emergency action that instantly drops any agent to L0 (observe only):

POST /api/v1/agents/:id/trust/kill

After a kill switch, the agent has a 24-hour cooldown before it can be promoted again. This prevents rapid flip-flopping during active security incidents.

Manual Demotion

POST /api/v1/agents/:id/trust/demote
{
  "targetLevel": 1,
  "reason": "Reducing permissions during maintenance"
}

Was this article helpful?