Autonomy vs Interactive

PraisonAI provides two distinct execution modes: Autonomy (multi-turn, self-correcting loops) and Interactive (single-turn, human-in-the-loop). Understanding their architecture helps you choose the right approach and extend the tool system correctly.

Execution Flow Comparison

Autonomy Mode Flow

When autonomy=True, the agent runs a multi-turn loop with safety infrastructure:

Interactive Mode Flow

In interactive mode, the human drives the loop — each message is a single-turn chat() call:

Key difference: In autonomy mode, the agent drives the iteration loop internally with safety checks. In interactive mode, the human drives the loop externally by sending messages. Both use the same chat() → tool executor underneath.

Feature Comparison

Dimension	Autonomy Mode	Interactive Mode
Entry point	`run_autonomous()`	`start()` → `chat()`
Turns	Multi-turn loop (up to `max_iterations`)	Single turn per call
Self-correction	✅ Doom loop detection + graduated recovery	❌ None
File safety	✅ Git snapshots before/after	❌ None
Completion signal	Completion promise pattern (`<promise>DONE</promise>`)	Return value
Stage escalation	direct → heuristic → planned → autonomous	N/A
Session persistence	Auto-saves after each iteration	Manual
Observability	Built-in event emission	Standard logging

Key insight: Autonomy mode is a multi-turn orchestration loop around the same chat() method. Both modes use identical tool execution — the difference is the loop and safety infrastructure above it.

Speed Profile

Init Overhead (one-time)

Component	Cost	Notes
`AutonomyConfig()`	~0ms	Simple dataclass
`AutonomyTrigger()`	~1-2ms	Lazy imports `EscalationTrigger`
`DoomLoopTracker()`	~1ms	Lazy imports `DoomLoopDetector`
`FileSnapshot`	~50-200ms	Only if `track_changes=True`
`ObservabilityHooks`	~1ms	Only if `observe=True`

With autonomy=True (defaults), init overhead is < 5ms since track_changes=False and observe=False by default.

Per-Iteration Overhead

Operation	Cost
Timeout check	~0μs
Doom-loop check	~0.1ms
Action recording	~0.1ms
Completion detection	~0.1ms
Session auto-save	0-5ms
Total	~0.5ms

Per-iteration overhead is ~0.5ms — negligible compared to LLM API calls (typically 1-30 seconds each). The real speed difference is the number of LLM calls, not framework overhead.

End-to-End Comparison

Metric	Non-Autonomy	Autonomy
Minimum LLM calls	1	1 (if completion detected on first turn)
Maximum LLM calls	1	20 (default `max_iterations`)
Typical for multi-step task	1 (all tools in one turn)	1-3 (re-injects if not “done”)
Overhead per call	0	~0.5ms

Important Behavioral Differences

Return type: AutonomyResult.__str__() returns .output, so print(result) works the same. But code that does if result: or len(result) may break — AutonomyResult is always truthy and has no __len__. Use str(result) or result.output.

Early completion risk: If the LLM says "I'm done searching" mid-task, autonomy mode stops early. For multi-step tasks, use structured completion signals:

Agent(autonomy={"completion_promise": "COMPLETED"})

Approval with autonomy=True: Default level is "suggest", which does NOT auto-approve tools. Only level="full_auto" auto-wires AutoApproveBackend.

Two-Layer Tool Architecture

Tools are provisioned at two independent layers. The CLI wrapper assembles tool lists and passes them as tools=[...] to the SDK’s Agent() constructor:

What each layer provides

ACP Tools Performance: ACP tools (acp_edit_file, acp_execute_command) go through a complex orchestration flow and can be slow (174s+ per operation). In autonomy mode (--autonomy full_auto), ACP tools are disabled by default for speed. Use --acp flag to explicitly enable them when needed.

CLI Wrapper (praisonai)

13 tools via get_interactive_tools():

ACP (4): create/edit/delete files, execute commands (disabled by default in autonomy)
LSP (4): symbols, definitions, references, diagnostics
Basic (5): read/write files, list, execute, search

Used by: praisonai tui, praisonai "prompt"

Core SDK (praisonaiagents)

16 tools when autonomy=True via AUTONOMY_PROFILE:

file_ops (7): read/write/list/copy/move/delete/info
shell (3): execute_command, list_processes, get_system_info
web (3): internet_search, search_web, web_crawl
code_intelligence (3): ast_grep search/rewrite/scan

Used by: Agent(autonomy=True) in Python

Built-in ToolProfiles

The SDK ships with composable profiles in tools/profiles.py:

Profile	Tools	Description
`code_intelligence`	3	ast-grep search, rewrite, scan
`file_ops`	7	read, write, list, copy, move, delete, get_file_info
`shell`	3	execute_command, list_processes, get_system_info
`web`	3	internet_search, search_web, web_crawl
`code_exec`	4	execute_code, analyze_code, format_code, lint_code
`schedule`	3	schedule_add, schedule_list, schedule_remove
`autonomy`	16	Composite: file_ops + shell + web + code_intelligence

Tools by entry point

Entry Point	Tools Available	Source
`praisonai tui`	13 (ACP + LSP + Basic)	CLI wrapper
`praisonai "prompt"`	13 + autonomy (16)	CLI wrapper + SDK
`praisonai tracker run`	30 (expanded set)	tracker.py
`Agent(autonomy=True)` in Python	16 (AUTONOMY_PROFILE)	Core SDK
`Agent()` in Python	0 (user-provided only)	—

Design Principles

The current architecture follows a layered separation pattern:

Core SDK stays minimal

The praisonaiagents package provides the agent runtime, tool execution, and LLM integration — but does not bundle default tools. This keeps the SDK lightweight and avoids opinionated defaults.

CLI wrapper adds batteries

The praisonai wrapper package adds ACP, LSP, file operations, and search tools for CLI users. It assembles toolsets and passes them as tools=[...] to the Agent constructor.

Tools are data, not hardcoded

Interactive tools are defined as groups in interactive_tools.py with a TOOL_GROUPS dictionary. New tools are added to a group, and all consumers automatically get them.

Why this is the best approach

SDK independence

The Core SDK has zero dependency on the CLI wrapper. Users embedding praisonaiagents in their own applications bring exactly the tools they need — no surprise defaults, no bloat.

Composable toolsets

Each entry point assembles its own toolset. praisonai tui loads ACP + LSP + Basic. praisonai tracker run loads a broader set. SDK users pass their own tools. This is intentional — different contexts need different capabilities.

Single source of truth

interactive_tools.py with get_interactive_tools() is the canonical provider. Both tui/app.py and main.py call this single function. Adding a new interactive tool means editing one file.

When to use which mode

Use Autonomy Mode

Multi-step tasks (refactoring, debugging)
Tasks that need self-correction
Batch/unattended execution
Tasks where you want git safety nets

agent = Agent(
    instructions="Refactor and test",
    autonomy=True,
    tools=[my_tools]
)
agent.start("Refactor the auth module")

Use Interactive Mode

Conversational Q&A
Quick one-off tasks
Human-guided workflows
Streaming responses

agent = Agent(
    instructions="Help with coding",
    tools=[my_tools]
)
agent.start("Explain this function")

Extending Tools

Using ToolProfiles (recommended)

Combine built-in profiles or register custom ones:

from praisonaiagents.tools.profiles import (
    resolve_profiles, register_profile, ToolProfile
)

# Combine built-in profiles
tools = resolve_profiles("file_ops", "web", "shell")
agent = Agent(tools=tools)

# Register a custom profile (e.g., from CLI wrapper)
register_profile(ToolProfile(
    name="acp",
    tools=["acp_create_file", "acp_edit_file",
           "acp_delete_file", "acp_execute_command"],
    description="Agentic Change Plan tools",
))

# Now use it alongside built-in profiles
tools = resolve_profiles("autonomy", "acp", "lsp")

Adding tools for CLI users

Add tools to interactive_tools.py:

# In praisonai/cli/features/interactive_tools.py
TOOL_GROUPS = {
    "basic": [read_file, write_file, ...],
    "acp": [acp_create_file, ...],
    "lsp": [lsp_list_symbols, ...],
    "my_group": [my_custom_tool],  # Add new group
}

Adding tools for SDK users

Pass tools directly — the SDK is tool-agnostic:

from praisonaiagents import Agent

def my_tool(query: str) -> str:
    """My custom tool."""
    return "result"

agent = Agent(
    instructions="Use tools wisely",
    tools=[my_tool],
    autonomy=True  # Gets 16 AUTONOMY_PROFILE tools + your tools
)

Autonomy Concepts

Configuration, stages, and doom loop detection

Autonomous Loops

Execution loop details and async support

Interactive Tools

ACP, LSP, and basic tool reference

Autonomy Modes

Suggest, auto-edit, and full-auto modes

Getting Started

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

​Execution Flow Comparison

​Autonomy Mode Flow

​Interactive Mode Flow

​Feature Comparison

​Speed Profile

​Init Overhead (one-time)

​Per-Iteration Overhead

​End-to-End Comparison

​Important Behavioral Differences

​Two-Layer Tool Architecture

​What each layer provides

CLI Wrapper (praisonai)

Core SDK (praisonaiagents)

​Built-in ToolProfiles

​Tools by entry point

​Design Principles

​Why this is the best approach

​When to use which mode

Use Autonomy Mode

Use Interactive Mode

​Extending Tools

​Using ToolProfiles (recommended)

​Adding tools for CLI users

​Adding tools for SDK users

​Related

Autonomy Concepts

Autonomous Loops

Interactive Tools

Autonomy Modes

Execution Flow Comparison

Autonomy Mode Flow

Interactive Mode Flow

Feature Comparison

Speed Profile

Init Overhead (one-time)

Per-Iteration Overhead

End-to-End Comparison

Important Behavioral Differences

Two-Layer Tool Architecture

What each layer provides

Built-in ToolProfiles

Tools by entry point

Design Principles

Why this is the best approach

When to use which mode

Extending Tools

Using ToolProfiles (recommended)

Adding tools for CLI users

Adding tools for SDK users

Related