Agent Autonomy

Control how independently agents operate - from suggestions to full automation

Autonomy controls how independently an agent operates — from requiring approval for every action to fully autonomous execution. The mode field determines whether start() uses a single chat() call ("caller") or a multi-turn loop ("iterative").

Which Mode Should I Choose?

Not sure which mode fits your task? Use this guide:

Mode	Best For	Example Prompt	What Happens
No autonomy	Questions, explanations, advice	”Explain authentication patterns”	Agent answers from knowledge — doesn’t touch files or run tools
Caller (default)	Single-shot automation, pipelines	”Search for X and save to file”	Agent uses tools in one turn, returns AutonomyResult
Iterative	Multi-step self-correction	”Refactor auth module and verify tests”	Agent loops with doom loop protection until done

Quick Start

1. Enable Autonomy

   from praisonaiagents import Agent
   
   # Caller mode (default) — single chat(), returns AutonomyResult
   agent = Agent(
       name="Autonomous Agent",
       instructions="You help with coding tasks",
       autonomy=True  # mode="caller" by default
   )
   
   result = agent.start("Refactor the authentication module")
   print(result.success)            # True
   print(result.completion_reason)  # "caller_mode"
   
2. With Configuration

   from praisonaiagents import Agent
   
   # Iterative mode — multi-turn autonomous loop
   agent = Agent(
       name="Full Auto Agent",
       instructions="You manage files and code",
       autonomy={
           "level": "full_auto",             # mode defaults to "iterative"
           "max_iterations": 30,
           "doom_loop_threshold": 5,
           "completion_promise": "DONE",
       }
   )
   
3. Explicit Mode Override

   from praisonaiagents import Agent
   
   # Force iterative loop even at suggest level
   agent = Agent(
       name="Iterative Agent",
       instructions="Work through complex tasks",
       autonomy={
           "mode": "iterative",
           "max_iterations": 15,
           "completion_promise": "COMPLETE",
       }
   )
   

---

Architecture

The autonomy system spans the Core SDK and Wrapper CLI, unified through bridging:

Key design decisions:

• Single source of truth: AutonomyLevel enum lives in the SDK; CLI’s AutonomyMode derives from it
• Bridge via env var: CLI’s FULL_AUTO mode sets PRAISONAI_AUTO_APPROVE=true for SDK approval
• AgentTeam propagation: AgentTeam(autonomy=...) propagates config to all managed agents
• Memory integration: run_autonomous() auto-saves sessions between iterations

---

Autonomy Stages

The agent automatically selects an execution stage based on task complexity:

Stage	Triggers	Behavior
direct	Simple questions, explanations	Single response
heuristic	File references, code blocks	Context-aware
planned	Edit/test intent	Plan before acting
autonomous	Multi-step, refactoring	Full iteration loop

---

How Completion Works

Understanding how the agent knows when it’s “done” is key to choosing the right mode.

The model decides when to stop by not requesting more tools. This is the same protocol used by ChatGPT, Claude, and all major LLM APIs.

Completion Signal	How It Works	Reliability
Tool completion	Model used tools, then stopped requesting more	⭐⭐⭐ Most reliable
Promise tag	Model outputs <promise>DONE</promise>	⭐⭐⭐ Explicit signal
Keyword detection	Model says “task completed”	⭐⭐ Can be inconsistent
No-tool turns	Model produces text without tools for 2+ turns	⭐⭐ Safety fallback
Max iterations	Reached the iteration limit	⭐ Last resort

For most tasks, caller mode is all you need — the model handles everything in one turn. Only use iterative mode when you need the agent to observe results and decide what to do next across multiple turns.

---

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,
    }
)

Option	Type	Default	Description
enabled	bool	True	Whether autonomy is enabled
level	str	"suggest"	Autonomy level: suggest, auto_edit, full_auto
mode	str	Smart default	"caller" (single chat) or "iterative" (loop). Defaults: suggest/auto_edit → "caller", full_auto → "iterative"
max_iterations	int	20	Maximum iterations (iterative mode only)
doom_loop_threshold	int	3	Repeated actions to trigger doom loop
auto_escalate	bool	True	Automatically escalate complexity
observe	bool	False	Emit 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 changes

Agent plans, executes, and verifies changes autonomously.

Research Tasks

Best for: Information gathering

Agent searches, synthesizes, and reports findings.

Bug Fixing

Best for: Debugging workflows

Agent analyzes, fixes, and tests iteratively.

Content Generation

Best for: Writing and editing

Agent drafts, refines, and polishes content.

---

Best Practices

Start with caller mode (default)

Most tasks complete in a single turn. The model calls all needed tools and summarizes — no iteration loop needed. Only switch to iterative when you need multi-turn self-correction.

Use completion promises for iterative mode

Set completion_promise for reliable termination in iterative mode. The agent outputs <promise>DONE</promise> when finished.

Keep doom loop threshold low

Keep doom_loop_threshold at 3-5 to prevent runaway agents and wasted resources.

Monitor with observe mode

Set observe=True during development to track agent behavior and stage escalation.

---

Related

Planning

Think before acting

Guardrails

Safety constraints