> ## 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
> Enable agents to operate independently with doom-loop protection and safety controls
Autonomy lets agents operate independently — detecting doom loops, escalating when stuck, and optionally running in a full-auto iterative mode.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Assistant",
instructions="You are an autonomous coding assistant.",
autonomy=True,
)
agent.start("Refactor the authentication module to use JWT tokens.")
```
The user delegates a coding task; the agent works independently, detects doom loops, and escalates to a human when stuck.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Autonomy Flow"
Task[📋 Task] --> Execute[⚙️ Execute]
Execute --> Check{🔍 Doom Loop?}
Check -->|No| Progress[✅ Progress]
Check -->|Yes| Escalate[🚨 Escalate]
Progress --> Complete[🎉 Complete]
Escalate --> Human[👤 Human Input]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Task input
class Execute,Check process
class Progress,Escalate,Complete,Human output
```
## Quick Start
Turn on autonomy with a single flag — defaults to the safe `suggest` level.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Coder",
instructions="You are an autonomous task-completion agent.",
autonomy=True,
)
agent.start("Write and test a Python function to merge sorted arrays.")
```
Pass a level name to unlock more independence.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Coder",
instructions="You are an autonomous coding agent.",
autonomy="full_auto",
)
agent.start("Build a REST API endpoint for user authentication.")
```
Use `AutonomyConfig` to tune iteration caps, doom-loop detection, and escalation.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, AutonomyConfig
agent = Agent(
name="Coder",
instructions="You are a precise autonomous agent.",
autonomy=AutonomyConfig(
level="auto_edit",
max_iterations=30,
doom_loop_threshold=5,
auto_escalate=True,
),
)
agent.start("Review and improve the test coverage for the payment module.")
```
***
## Autonomy Levels
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{How much autonomy?}
Q -->|Suggestions only| Suggest[suggest\ndefault — propose changes, user approves]
Q -->|Auto-edit files| AutoEdit[auto_edit\ncan edit files automatically]
Q -->|Full autonomous loop| FullAuto[full_auto\niterative loop with completion detection]
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef level fill:#6366F1,stroke:#7C90A0,color:#fff
class Q decision
class Suggest,AutoEdit,FullAuto level
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Autonomy
participant Safety
User->>Agent: task
loop Autonomy iterations
Agent->>Autonomy: Execute step
Autonomy->>Safety: Doom loop check
alt Doom loop detected
Safety-->>Agent: Escalate to user
Agent-->>User: Request clarification
else No doom loop
Autonomy-->>Agent: Continue
end
end
Agent-->>User: Task complete
```
| Phase | What happens |
| --------------- | --------------------------------------------------------- |
| 1. Execute | Agent takes action toward the goal |
| 2. Safety check | Doom loop tracker monitors for repeated identical actions |
| 3. Escalate | If stuck, agent asks user for guidance instead of looping |
| 4. Complete | Iterative mode detects task completion signal |
***
## Configuration Options
Full list of options, types, and defaults — `AutonomyConfig`
The most common options at a glance:
| Option | Type | Default | Description |
| --------------------- | ------------- | ----------- | -------------------------------------------- |
| `level` | `str` | `"suggest"` | `"suggest"`, `"auto_edit"`, or `"full_auto"` |
| `max_iterations` | `int` | `20` | Max iterations before stopping |
| `doom_loop_threshold` | `int` | `3` | Repeated actions before doom loop detection |
| `auto_escalate` | `bool` | `True` | Automatically escalate when stuck |
| `completion_promise` | `str \| None` | `None` | Signal text that marks task completion |
***
## Common Patterns
### Pattern 1 — Auto-edit mode for coding tasks
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, AutonomyConfig
agent = Agent(
instructions="You are a senior software engineer.",
autonomy=AutonomyConfig(
level="auto_edit",
max_iterations=15,
doom_loop_threshold=3,
),
)
response = agent.start("Add input validation to all API endpoints in the users module.")
print(response)
```
### Pattern 2 — Full-auto iterative mode
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, AutonomyConfig
agent = Agent(
instructions="You are an autonomous DevOps agent.",
autonomy=AutonomyConfig(
level="full_auto",
completion_promise="DEPLOYMENT_COMPLETE",
max_iterations=50,
),
)
agent.start("Deploy the application to staging and run smoke tests.")
```
***
## Best Practices
Start with `autonomy=True` (level `suggest`) to see what the agent proposes before giving it permission to edit files or run in a full loop. Graduate to `auto_edit` or `full_auto` when you trust the agent's behavior.
The default threshold of 3 means 3 identical actions trigger escalation. Lower this to 2 for high-stakes tasks, or raise it to 5 for tasks where retrying the same action is expected behavior (like polling).
In `full_auto` mode, the agent loops until it detects completion. Set `completion_promise="TASK_COMPLETE"` and instruct the agent to output this signal when done, giving you clean loop termination.
***
## Related
Autonomy Loop — deep dive into iterative autonomy mode
Planning — plan before acting on complex requests