Skip to main content
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:
StageNameDescriptionUse Case
0DIRECTNo tools, immediate responseSimple questions
1HEURISTICTool selection based on signalsFile references, code blocks
2PLANNEDLightweight planningEdit/test/build tasks
3AUTONOMOUSFull autonomous loopMulti-step, refactoring

​
Quick Start

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

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): 
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

SignalTrigger
simple_question”what is”, “define”, “explain”
complex_keywords”analyze”, “refactor”, “optimize”
file_referencesFile paths like src/main.py
code_blocksMarkdown code blocks
edit_intent”edit”, “modify”, “fix”
test_intent”test”, “pytest”, “verify”
multi_stepMultiple steps or “and then”
refactor_intent”refactor”, “restructure”

​
Stage Recommendation

The agent recommends execution stages based on detected signals: 
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: 
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: 
# 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

​
Escalation Components

The escalation pipeline includes several safety and control components under praisonaiagents/escalation/:
  • Doom Loop Detector — pattern-based detection of identical calls and no-progress scenarios
  • Loop Guard (PR #1834) — always-on idempotency-aware tool-call guardrails initialised on every Agent. See Loop Guard.
  • Pipeline orchestration — coordinates escalation triggers and recovery actions
  • Observability hooks — monitoring and metrics for escalation events