AutonomyConfig

Control how autonomous agents operate, including autonomy levels, doom-loop detection, memory integration, and completion signals.

Quick Start

Simple Enable

Enable autonomy with defaults:

from praisonaiagents import Agent

agent = Agent(
    name="Autonomous Agent",
    instructions="Work autonomously",
    autonomy=True
)

With Configuration

Configure autonomy behavior:

from praisonaiagents import Agent, AutonomyConfig

agent = Agent(
    name="Autonomous Agent",
    instructions="Work autonomously",
    autonomy=AutonomyConfig(
        level="auto_edit",
        max_iterations=30,
        doom_loop_threshold=5,
        auto_escalate=True,
    )
)

With Memory Integration

Autonomy loops auto-save sessions between iterations when memory is enabled:

from praisonaiagents import Agent, AutonomyConfig

agent = Agent(
    name="Persistent Agent",
    instructions="Work autonomously with memory",
    autonomy=AutonomyConfig(max_iterations=20),
    memory=True,
    auto_save="my_session",
)

Configuration Options

from praisonaiagents import AutonomyConfig, AutonomyLevel

config = AutonomyConfig(
    # Core settings
    enabled=True,                      # Enable/disable autonomy
    level="suggest",                   # Autonomy level (suggest, auto_edit, full_auto)
    max_iterations=20,                 # Max loop iterations before stopping
    
    # Doom loop detection
    doom_loop_threshold=3,             # Repeated actions before doom loop triggers
    auto_escalate=True,                # Escalate to user when stuck
    
    # Completion signals
    completion_promise="TASK_DONE",    # Structured promise tag for completion
    
    # Observability
    observe=False,                     # Emit trace events
    
    # Context management
    clear_context=False,               # Clear chat history between iterations
    
    # Verification
    verification_hooks=None,           # List of VerificationHook instances
)

Parameter	Type	Default	Description
`enabled`	`bool`	`True`	Whether autonomy is enabled
`level`	`str`	`"suggest"`	Autonomy level (`suggest`, `auto_edit`, `full_auto`)
`max_iterations`	`int`	`20`	Maximum iterations before stopping
`doom_loop_threshold`	`int`	`3`	Number of repeated actions to trigger doom loop
`auto_escalate`	`bool`	`True`	Automatically escalate complexity when stuck
`completion_promise`	`str \| None`	`None`	Structured completion signal (e.g. `"DONE"`)
`observe`	`bool`	`False`	Emit observability events during loop
`clear_context`	`bool`	`False`	Clear chat history between iterations
`verification_hooks`	`list \| None`	`None`	VerificationHook instances for output verification

sandbox= on AutonomyConfig is not exposed. AutonomyConfig carries a sandbox: Optional[SandboxConfig] field for forward compatibility; nothing currently reads it and no sandbox is auto-enabled at any autonomy level. Pass Agent(sandbox=…) to enable the explicit agent.execute_code() API; to isolate a whole workflow in a real container, use AgentFlow(run_on=…). See Placement.

Autonomy Levels

Level	Enum Value	Description
`suggest`	`AutonomyLevel.SUGGEST`	Agent suggests actions, user approves
`auto_edit`	`AutonomyLevel.AUTO_EDIT`	Agent edits files, user reviews critical changes
`full_auto`	`AutonomyLevel.FULL_AUTO`	Agent operates fully autonomously

from praisonaiagents import AutonomyLevel

# Use enum or string - both work
config = AutonomyConfig(level=AutonomyLevel.AUTO_EDIT.value)
config = AutonomyConfig(level="auto_edit")

Common Patterns

Pattern 1: Safe Autonomous Agent

from praisonaiagents import Agent, AutonomyConfig

agent = Agent(
    name="Safe Agent",
    instructions="Work carefully",
    autonomy=AutonomyConfig(
        level="suggest",
        max_iterations=10,
        doom_loop_threshold=3,
        auto_escalate=True,
    )
)

Pattern 2: Full Autonomy with Completion Promise

from praisonaiagents import Agent, AutonomyConfig

agent = Agent(
    name="Full Auto Agent",
    instructions="Complete autonomy",
    autonomy=AutonomyConfig(
        level="full_auto",
        max_iterations=50,
        completion_promise="ALL_DONE",
    )
)

# Unified API — start() automatically uses the autonomous loop!
result = agent.start("Build the feature end to end")
print(f"Success: {result.success}, Iterations: {result.iterations}")

Pattern 3: Multi-Agent Autonomy Propagation

from praisonaiagents import Agent, AgentTeam, AutonomyConfig

researcher = Agent(name="Researcher", instructions="Research topics")
writer = Agent(name="Writer", instructions="Write articles")

# AgentTeam propagates autonomy to all agents
team = AgentTeam(
    agents=[researcher, writer],
    autonomy=AutonomyConfig(max_iterations=30),
)

Best Practices

Start with Suggest Level

Begin with suggest level and increase autonomy as you gain confidence.

Use Doom Loop Detection

Keep doom_loop_threshold at 3-5 to prevent agents from repeating the same action.

Enable Memory for Long Sessions

Combine autonomy=True with memory=True and auto_save to persist progress between iterations.

Use Completion Promises

Use completion_promise for structured completion signals instead of relying on keyword detection.

Autonomy Loop

Learn about the autonomy loop

Ralph Loops

Autonomous execution pattern

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Configuration Options

Autonomy Levels

Common Patterns

Pattern 1: Safe Autonomous Agent

Pattern 2: Full Autonomy with Completion Promise

Pattern 3: Multi-Agent Autonomy Propagation

Best Practices

Autonomy Loop

Ralph Loops

​Quick Start

​Configuration Options

​Autonomy Levels

​Common Patterns

​Pattern 1: Safe Autonomous Agent

​Pattern 2: Full Autonomy with Completion Promise

​Pattern 3: Multi-Agent Autonomy Propagation

​Best Practices

​Related

Autonomy Loop

Ralph Loops

Quick Start

Configuration Options

Autonomy Levels

Common Patterns

Pattern 1: Safe Autonomous Agent

Pattern 2: Full Autonomy with Completion Promise

Pattern 3: Multi-Agent Autonomy Propagation

Best Practices

Related