Skip to main content
Autonomy controls how independently an agent operates - from requiring approval for every action to fully autonomous execution.

​
Quick Start

1

Enable Autonomy

from praisonaiagents import Agent

agent = Agent(
    name="Autonomous Agent",
    instructions="You help with coding tasks",
    autonomy=True  # Enable with defaults
)

agent.start("Refactor the authentication module")
2

With Configuration

from praisonaiagents import Agent

agent = Agent(
    name="Controlled Agent",
    instructions="You manage files and code",
    autonomy={
        "max_iterations": 30,           # Max iterations
        "doom_loop_threshold": 5,       # Detect stuck loops
        "auto_escalate": True,          # Escalate on failures
    }
)

​
Autonomy Stages

The agent automatically selects an execution stage based on task complexity:
StageTriggersBehavior
directSimple questions, explanationsSingle response
heuristicFile references, code blocksContext-aware
plannedEdit/test intentPlan before acting
autonomousMulti-step, refactoringFull iteration loop

​
Configuration Options

from praisonaiagents import Agent

# Using dict config
agent = Agent(
    instructions="You help with coding tasks",
    autonomy={
        "max_iterations": 30,
        "doom_loop_threshold": 5,
        "auto_escalate": True,
    }
)
OptionTypeDefaultDescription
enabledboolTrueWhether autonomy is enabled
max_iterationsint20Maximum iterations before stopping
doom_loop_thresholdint3Repeated actions to trigger doom loop
auto_escalateboolTrueAutomatically escalate complexity
observeboolFalseEmit observability events

​
Doom Loop Detection

Prevents agents from getting stuck in repetitive failure patterns: 
agent = Agent(
    instructions="You fix bugs",
    autonomy={
        "doom_loop_threshold": 3,  # Stop after 3 similar failures
    }
)

​
Escalation Pipeline

When an agent can’t complete a task, it escalates: 
agent = Agent(
    instructions="You solve complex problems",
    autonomy={
        "auto_escalate": True,  # Enable escalation
        "max_iterations": 20,   # Max attempts before escalating
    }
)

​
Signal Detection

Autonomy uses heuristics to detect task complexity: 
# Signals detected from prompts
SIMPLE_KEYWORDS = {"what is", "explain", "describe"}
COMPLEX_KEYWORDS = {"refactor", "implement", "debug", "fix"}
EDIT_KEYWORDS = {"edit", "modify", "change", "update"}

​
Use Cases

Code Refactoring

Best for: Multi-step code changesAgent plans, executes, and verifies changes autonomously.

Research Tasks

Best for: Information gatheringAgent searches, synthesizes, and reports findings.

Bug Fixing

Best for: Debugging workflowsAgent analyzes, fixes, and tests iteratively.

Content Generation

Best for: Writing and editingAgent drafts, refines, and polishes content.

​
Best Practices

Begin with lower max_iterations and increase as needed for complex tasks.
Keep doom_loop_threshold low (3-5) to prevent runaway agents and wasted resources.
Enable auto_escalate to let agents escalate to stronger models when stuck.
Set observe=True during development to track agent behavior.

Planning

Think before acting

Guardrails

Safety constraints