Autonomy

Control how much freedom agents have

Agents can operate at different autonomy levels – from suggesting actions to fully autonomous.

Quick Start

1. Simple Usage

   import { Agent } from 'praisonai';
   
   const agent = new Agent({
     instructions: 'You help with code',
     autonomy: 'suggest'  // Only suggests, never acts
   });
   
   await agent.chat('Fix the bug in app.js');
   // → "I suggest changing line 42 to..."

2. With Configuration

   const agent = new Agent({
     instructions: 'You complete tasks autonomously',
     autonomy: 'full_auto'
   });
   
   await agent.chat('Update the readme');
   // → Agent edits the file directly

User Interaction Flow

Configuration Levels

// Level 1: String - Named mode
const agent = new Agent({
  autonomy: 'suggest'  // 'suggest', 'auto_edit', 'full_auto'
});

// Level 2: Dict - With limits
const agent = new Agent({
  autonomy: {
    mode: 'auto_edit',
    maxEdits: 10,
    requireConfirmation: true
  }
});

// Level 3: Instance - Full control
import { AutonomyManager } from 'praisonai';

const manager = new AutonomyManager({
  mode: 'full_auto',
  policies: {
    allowFileEdits: true,
    allowCommands: false
  }
});

Autonomy Modes

Team-wide Autonomy

An AgentTeam can hand every member the same autonomy level — but a member’s own choice always wins.

import { Agent, AgentTeam } from 'praisonai';

const researcher = new Agent({ instructions: 'Research the topic' });
const writer = new Agent({ instructions: 'Write the article' });

// Every member without its own autonomy adopts 'full_auto'
const team = new AgentTeam({
  agents: [researcher, writer],
  autonomy: 'full_auto',
});
await team.start();

A member’s own autonomy wins over the team’s — the team only reaches members that declared none. Silently widening a permission an agent set for itself is the direction that causes harm.

const cautious = new Agent({ instructions: 'Careful edits', autonomy: 'suggest' });
const bold = new Agent({ instructions: 'Ship it' });

new AgentTeam({ agents: [cautious, bold], autonomy: 'full_auto' });
// cautious keeps 'suggest'; bold adopts 'full_auto'

A propagated prompting level (anything not full_auto) also creates the approval gate on adopted members: an ApprovalManager with a CLI prompt handler, plus a DoomLoopTracker. This is what makes propagation actually pause execution instead of being recorded and ignored.

Under the hood, the team calls Agent.adoptAutonomy(config) on each member. It returns false when the agent already has its own autonomy (no-op), and true when adopted.

API Reference

Best Practices

Related