Skip to main content
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:
ModeBest ForExample PromptWhat Happens
No autonomyQuestions, 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
IterativeMulti-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:
StageTriggersBehavior
directSimple questions, explanationsSingle response
heuristicFile references, code blocksContext-aware
plannedEdit/test intentPlan before acting
autonomousMulti-step, refactoringFull 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 SignalHow It WorksReliability
Tool completionModel used tools, then stopped requesting more⭐⭐⭐ Most reliable
Promise tagModel outputs <promise>DONE</promise>⭐⭐⭐ Explicit signal
Keyword detectionModel says “task completed”⭐⭐ Can be inconsistent
No-tool turnsModel produces text without tools for 2+ turns⭐⭐ Safety fallback
Max iterationsReached 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,
    }
)
OptionTypeDefaultDescription
enabledboolTrueWhether autonomy is enabled
levelstr"suggest"Autonomy level: suggest, auto_edit, full_auto
modestrSmart default"caller" (single chat) or "iterative" (loop). Defaults: suggest/auto_edit → "caller", full_auto → "iterative"
max_iterationsint20Maximum iterations (iterative mode only)
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

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.
Set completion_promise for reliable termination in iterative mode. The agent outputs <promise>DONE</promise> when finished.
Keep doom_loop_threshold at 3-5 to prevent runaway agents and wasted resources.
Set observe=True during development to track agent behavior and stage escalation.

Planning

Think before acting

Guardrails

Safety constraints