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

# Agent Autonomy

> Agent-centric progressive escalation from direct response to autonomous mode

Agent Autonomy implements an "advanced-by-default, fast-by-default" strategy that automatically adjusts execution complexity based on task signals. All features are accessed through the `Agent` class.

## Overview

The agent provides 4 autonomy stages:

| Stage | Name       | Description                     | Use Case                     |
| ----- | ---------- | ------------------------------- | ---------------------------- |
| 0     | DIRECT     | No tools, immediate response    | Simple questions             |
| 1     | HEURISTIC  | Tool selection based on signals | File references, code blocks |
| 2     | PLANNED    | Lightweight planning            | Edit/test/build tasks        |
| 3     | AUTONOMOUS | Full autonomous loop            | Multi-step, refactoring      |

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Create an agent with autonomy enabled
agent = Agent(
    instructions="You are a helpful coding assistant.",
    llm="gpt-4o-mini",
    autonomy=True  # Enable autonomy features
)

# Analyze a prompt (no API call, fast heuristics)
stage = agent.get_recommended_stage("What is Python?")
print(f"Recommended stage: {stage}")  # direct

# Get signals from a prompt
signals = agent.analyze_prompt("Refactor the auth module")
print(f"Signals: {signals}")  # {'refactor_intent', 'complex_keywords'}

# Use the agent normally - autonomy features work automatically
response = agent.chat("What is Python?")
print(response)
```

## Custom Configuration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Create agent with custom autonomy config
agent = Agent(
    instructions="You are a coding assistant.",
    autonomy={
        "max_iterations": 30,
        "doom_loop_threshold": 5,
        "auto_escalate": True
    }
)

print(f"Autonomy enabled: {agent.autonomy_enabled}")
print(f"Config: {agent.autonomy_config}")
```

## Signal Detection

The agent detects signals from prompts using fast heuristics (no LLM calls):

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(instructions="Assistant", autonomy=True)

# Analyze different prompts
signals = agent.analyze_prompt("What is Python?")
# Returns: {'simple_question'}

signals = agent.analyze_prompt("Read src/main.py and explain it")
# Returns: {'file_references'}

signals = agent.analyze_prompt("Refactor the auth module and add tests")
# Returns: {'edit_intent', 'test_intent', 'refactor_intent', 'complex_keywords'}
```

### Available Signals

| Signal             | Trigger                           |
| ------------------ | --------------------------------- |
| `simple_question`  | "what is", "define", "explain"    |
| `complex_keywords` | "analyze", "refactor", "optimize" |
| `file_references`  | File paths like `src/main.py`     |
| `code_blocks`      | Markdown code blocks              |
| `edit_intent`      | "edit", "modify", "fix"           |
| `test_intent`      | "test", "pytest", "verify"        |
| `multi_step`       | Multiple steps or "and then"      |
| `refactor_intent`  | "refactor", "restructure"         |

## Stage Recommendation

The agent recommends execution stages based on detected signals:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(instructions="Assistant", autonomy=True)

# Simple question → DIRECT stage
stage = agent.get_recommended_stage("What is Python?")
print(stage)  # "direct"

# File reference → HEURISTIC stage
stage = agent.get_recommended_stage("Read src/main.py")
print(stage)  # "heuristic"

# Edit task → PLANNED stage
stage = agent.get_recommended_stage("Fix the bug in auth.py")
print(stage)  # "planned"

# Complex refactor → AUTONOMOUS stage
stage = agent.get_recommended_stage("Refactor auth and add tests")
print(stage)  # "autonomous"
```

## Doom Loop Detection

The agent includes built-in doom loop detection to prevent infinite loops:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Create agent with custom doom loop threshold
agent = Agent(
    instructions="You are a coding assistant.",
    autonomy={"doom_loop_threshold": 3}  # Trigger after 3 repeated actions
)

# The agent automatically tracks actions and detects loops
# During execution, if a doom loop is detected:
# - The agent will break the loop
# - Report the issue to the user
# - Suggest a different approach

# You can also check manually:
if agent._is_doom_loop():
    print("Doom loop detected!")
    agent._reset_doom_loop()  # Reset for next task
```

## CLI Usage

Use autonomy features from the command line:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple question (uses DIRECT stage automatically)
praisonai "What is Python?"

# Complex task (escalates to AUTONOMOUS stage)
praisonai "Refactor the auth module and add tests"

# With explicit autonomy options
praisonai chat --autonomy
```

## Best Practices

1. **Use Agent(autonomy=True)** - Enable autonomy features on your agent
2. **Let the agent decide** - The agent automatically selects the right stage
3. **Custom thresholds** - Adjust doom\_loop\_threshold for your use case
4. **Check signals** - Use analyze\_prompt() to understand task complexity
5. **All agent-centric** - No standalone pipeline objects needed

## Related

* [Doom Loop Detection](/docs/features/doom-loop-detection)
* [Subagent Delegation](/docs/features/subagent-delegation)