Autonomous Loops - PraisonAI

Autonomous loops let agents work iteratively on complex tasks, automatically stopping when they signal completion or reach limits.

Mode matters: Autonomous loops use mode="iterative". This is the default for level="full_auto". With autonomy=True (default level), mode is "caller" (single chat) — set mode="iterative" explicitly or use level="full_auto" to enable loops.

from praisonaiagents import Agent

agent = Agent(
    name="worker",
    instructions="Iterate until the task is complete.",
    autonomy={"level": "full_auto"},
)
agent.start("Fix the failing unit tests.")

The user assigns a multi-step task; the agent loops until tool completion, a promise match, or a safety limit stops the run.

The most common completion path is tool completion — the model calls tools to do the work, then produces a summary without requesting more tools. This is the same mechanism ChatGPT and Claude use.

Quick Start

Simple Usage

from praisonaiagents import Agent

# full_auto defaults to mode="iterative"
agent = Agent(
    name="builder",
    instructions="Build the requested feature",
    autonomy="full_auto"
)

result = agent.start("Create a REST API with user authentication")

print(f"Success: {result.success}")
print(f"Iterations: {result.iterations}")

from praisonaiagents import Agent

agent = Agent(
    name="builder",
    instructions="""Build the feature. When done, output:
    <promise>DONE</promise>""",
    autonomy={
        "mode": "iterative",
        "max_iterations": 20,
        "completion_promise": "DONE",
    }
)

result = agent.start("Create a calculator module")

from praisonaiagents import Agent

agent = Agent(
    name="builder",
    instructions="Work on the task. Use files for state.",
    autonomy={
        "level": "full_auto",
        "max_iterations": 15,
        "completion_promise": "COMPLETE",
        "clear_context": True,  # Fresh memory each iteration
    }
)

result = agent.start("Refactor the auth module")

Unified API: When mode="iterative", agent.start() automatically runs the autonomous loop with 16 default tools (file ops, shell, web search, ast-grep) via the AUTONOMY_PROFILE. No need to call run_autonomous() separately!

With Configuration

Use an explicit autonomy dict for iterative mode, completion_promise, and optional clear_context — see the additional tabs in the code group above.

How It Works

Behind the scenes: The inner tool loop handles ALL tool calls in a single turn. The model keeps calling tools until it’s satisfied, then stops. The outer loop detects this and returns immediately — no unnecessary extra iterations.

Key Features

Completion Promise

Agent signals “done” with a promise tag containing TEXT

Context Clearing

Fresh memory each iteration forces file-based state

Doom Loop Detection

Automatically stops on repeated identical actions

Iteration Limits

Prevents runaway execution with configurable max

Configuration

AutonomyConfig Options

Option	Type	Default	Description
`max_iterations`	int	20	Maximum loop iterations
`completion_promise`	str	None	Text to detect in promise tags
`clear_context`	bool	False	Clear chat history between iterations
`doom_loop_threshold`	int	3	Repeated actions before stopping
`level`	str	`"suggest"`	Autonomy level: `suggest`, `auto_edit`, `full_auto`
`auto_escalate`	bool	True	Automatically escalate task complexity
`observe`	bool	False	Emit observability events

Using Config Dict

agent = Agent(
    name="worker",
    instructions="Complete the task",
    autonomy={
        "max_iterations": 30,
        "completion_promise": "FINISHED",
        "clear_context": True,
        "doom_loop_threshold": 5
    }
)

CLI Usage

Basic
With Promise
With Context Clearing
With Timeout

praisonai loop "Build a REST API" -n 5

praisonai loop "Refactor auth module" -p DONE -v

praisonai loop "Implement feature X" -p COMPLETE -c -n 20

praisonai loop "Debug the issue" -t 300 -v

CLI Options

Flag	Description
`-n, --max-iterations`	Maximum iterations (default: 10)
`-p, --completion-promise`	Promise text to signal completion
`-c, --clear-context`	Clear chat history between iterations
`-t, --timeout`	Timeout in seconds
`-m, --model`	LLM model to use
`-v, --verbose`	Show verbose output

Result Object

result = agent.start(prompt)  # when autonomy=True

# Available fields
result.success          # bool - Task completed successfully
result.output           # str - Final response
result.completion_reason # str - "tool_completion", "promise", "caller_mode", "max_iterations", "doom_loop", "timeout", "error"
result.iterations       # int - Number of iterations executed
result.duration_seconds # float - Total execution time
result.started_at       # str - ISO 8601 timestamp when execution started
result.actions          # list - Actions taken each iteration
result.error            # str | None - Error message if failed

How Completion Detection Works

Completion Reasons

tool_completion (most common)

The model used tools to complete the task and then produced a summary response without requesting more tools. This is the most reliable completion signal — it’s the same mechanism used by ChatGPT and all major LLM APIs.

caller_mode

Agent was in caller mode (autonomy=True default). Single chat() call wrapped in AutonomyResult.

promise

Agent output contained a promise tag with TEXT matching the configured promise.

goal

Agent output contained completion keywords like “task completed” or “done”.

no_tool_calls

The model produced text without calling any tools for 2+ consecutive turns — indicates it has nothing left to do.

max_iterations

Reached the maximum iteration limit without completion signal.

doom_loop

Detected repeated identical actions (agent stuck in a loop).

timeout

Execution exceeded the configured timeout.

needs_help

Doom loop recovery exhausted — task needs human guidance.

error

An error occurred during execution.

Recommended Workflow

Use Completion Promises

Always set a completion_promise for reliable termination instead of relying on keyword detection.

Enable Context Clearing for Long Tasks

Use clear_context=True for tasks that should rely on file state rather than conversation memory.

Set Reasonable Limits

Configure max_iterations based on task complexity. Start low and increase if needed.

Include Promise in Instructions

Tell the agent to output the promise tag when done:

instructions="When finished, output DONE in a promise tag"

Async Execution

Run autonomous loops asynchronously for concurrent agent execution:

import asyncio
from praisonaiagents import Agent

async def main():
    agent = Agent(
        name="async_worker",
        instructions="Complete the task. Output <promise>DONE</promise> when finished.",
        autonomy={
            "max_iterations": 10,
            "completion_promise": "DONE",
        }
    )
    
    # astart() automatically uses autonomous loop when autonomy=True
    result = await agent.astart("Build a calculator")
    
    print(f"Success: {result.success}")
    print(f"Started: {result.started_at}")

asyncio.run(main())

import asyncio
from praisonaiagents import Agent

async def main():
    agent1 = Agent(
        name="researcher", 
        instructions="Research the topic", 
        autonomy={"completion_promise": "DONE"}
    )
    agent2 = Agent(
        name="writer", 
        instructions="Write content", 
        autonomy={"completion_promise": "DONE"}
    )
    
    # Run both agents concurrently with unified API
    results = await asyncio.gather(
        agent1.astart("Research AI trends"),
        agent2.astart("Write a blog post")
    )
    
    for i, result in enumerate(results):
        print(f"Agent {i+1}: {result.completion_reason}")

asyncio.run(main())

When autonomy=True, astart() automatically routes to the async autonomous loop, enabling true concurrent execution of multiple agents.

Memory Integration

Autonomous loops automatically save sessions between iterations when memory is enabled. This ensures progress is persisted even if the loop is interrupted.

from praisonaiagents import Agent

agent = Agent(
    name="persistent_worker",
    instructions="Work on the task. Output <promise>DONE</promise> when finished.",
    autonomy={
        "completion_promise": "DONE",
        "max_iterations": 20,
    },
    memory=True,
    auto_save="project_session",
)

# Unified API — start() handles everything!
result = agent.start("Refactor the auth module")
# Session is auto-saved after every iteration

_auto_save_session() is a no-op when memory or auto_save is not configured, so there is zero overhead for agents without memory.

Example: Self-Improving Code

from praisonaiagents import Agent

agent = Agent(
    name="improver",
    instructions="""You are a code improvement agent.
    
    1. Read the current code
    2. Identify one improvement
    3. Make the change
    4. Verify it works
    5. If no more improvements needed, output <promise>OPTIMIZED</promise>
    """,
    autonomy={
        "max_iterations": 10,
        "completion_promise": "OPTIMIZED",
        "clear_context": True,
    },
    tools=[read_file, write_file, run_tests]
)

# Just call start() - autonomy config handles everything!
result = agent.start("Optimize the performance of src/utils.py")

if result.success:
    print(f"Code optimized in {result.iterations} iterations")
    print(f"Started: {result.started_at}")
else:
    print(f"Stopped: {result.completion_reason}")

Best Practices

Choose the mode that matches the task

Loops only run in mode="iterative". autonomy=True uses mode="caller" (a single chat), so set level="full_auto" or pass mode="iterative" explicitly when you want the agent to keep working across turns. Use single-turn mode for quick answers to avoid unnecessary iterations.

Give the agent a clear completion signal

The loop stops on tool completion, a promise match, or a safety limit. Write instructions that produce a definite end state (“stop when all tests pass”) so the agent hits tool completion instead of drifting until it reaches the iteration cap.

Keep doom-loop detection on

Doom-loop detection halts an agent that repeats the same unproductive action. Leave it enabled for long-running tasks; it’s the safety net that turns a runaway loop into a clean completion_reason you can inspect.

Check the RunOutcome, don't assume success

start() returns a result with success, iterations, and completion_reason. Branch on result.success and log completion_reason so a limit-reached run is handled distinctly from genuine completion.

Autonomous Workflows

Core autonomy configuration

Background Tasks

Run agents in the background

​Quick Start

​How It Works

​Key Features

Completion Promise

Context Clearing

Doom Loop Detection

Iteration Limits

​Configuration

​AutonomyConfig Options

​Using Config Dict

​CLI Usage

​CLI Options

​Result Object

​How Completion Detection Works

​Completion Reasons

​Recommended Workflow

​Async Execution

​Memory Integration

​Example: Self-Improving Code

​Best Practices

​Related

Autonomous Workflows

Background Tasks

Quick Start

How It Works

Key Features

Configuration

AutonomyConfig Options

Using Config Dict

CLI Usage

CLI Options

Result Object

How Completion Detection Works

Completion Reasons

Recommended Workflow

Async Execution

Memory Integration

Example: Self-Improving Code

Best Practices

Related