> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Autonomy

> Control how much freedom agents have

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

> [!WARNING]
>
> `autonomy` is accepted on a `Task` for Python-SDK parity but is **not yet implemented** in the TypeScript SDK — passing it emits a `[praisonai] … not yet honoured` notice and has no effect. This feature is Python-only for now.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Autonomy Levels"
        A[💬 Suggest] --> B[📝 Auto Edit]
        B --> C[🚀 Full Auto]
    end
    
    classDef suggest fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef edit fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef auto fill:#10B981,stroke:#7C90A0,color:#fff
    
    class A suggest
    class B edit
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    class C auto
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

## Quick Start

**1. Simple Usage**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant System
    
    User->>Agent: "Fix the bug"
    
    alt suggest mode
        Agent-->>User: "I suggest..."
    else auto_edit mode
        Agent->>User: "Apply this change? [y/n]"
        User->>Agent: "Yes"
        Agent->>System: Apply change
    else full_auto mode
        Agent->>System: Apply change
        Agent-->>User: "Done!"
    end
```

***

## Configuration Levels

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// 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

| Mode | Behavior |
| - | - |
| `suggest` | Only suggests, never acts |
| `auto_edit` | Asks before making changes |
| `full_auto` | Acts without asking |

***

## Team-wide Autonomy

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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Team as AgentTeam
    participant Member as Member Agent
    participant Gate as ApprovalManager

    Team->>Member: adoptAutonomy('suggest')
    Member->>Gate: create (CLI prompt + DoomLoopTracker)
    Gate-->>Member: gate ready
    Member-->>Team: adopted
```

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.

> [!NOTE]
>
> `autonomy: false`, or no `autonomy` at all, leaves every member untouched.

***

## API Reference

> [card] [AgentConfig](https://praison.ai/docs/sdk/reference/typescript/classes/AgentConfig.md)
>
> Agent configuration including autonomy

***

## Best Practices

> [accordion] Start with suggest
>
> Begin in suggest mode until you trust the agent's decisions.

> [accordion] Use auto\_edit for productivity
>
> Auto-edit balances speed with human oversight.

> [accordion] Reserve full\_auto for safe tasks
>
> Only use full\_auto for well-tested, low-risk workflows.

***

## Related

> [card] [Approval](https://praison.ai/docs/js/approval.md)
>
> Human approval

> [card] [Guardrails](https://praison.ai/docs/js/guardrails.md)
>
> Safety limits


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.