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").

Diagram

Which Mode Should I Choose?

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

Diagram

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

Enable Autonomy

python

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"

With Configuration

python

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

Explicit Mode Override

python

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:

Diagram

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:

Diagram

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.

Diagram

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

Configuration Options

python

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:

Diagram

python

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:

Diagram

python

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:

python

# Signals detected from prompts
SIMPLE_KEYWORDS = {"what is", "explain", "describe"}
COMPLEX_KEYWORDS = {"refactor", "implement", "debug", "fix"}
EDIT_KEYWORDS = {"edit", "modify", "change", "update"}

Diagram

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.

Planning

Think before acting

Guardrails

Safety constraints

Agent Autonomy

Which Mode Should I Choose?

Quick Start

Architecture

Autonomy Stages

How Completion Works

Configuration Options

Doom Loop Detection

Escalation Pipeline

Signal Detection

Use Cases

Best Practices

Related