Skip to main content
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

DimensionAutonomy ModeInteractive Mode
Entry pointrun_autonomous()start() → chat()
TurnsMulti-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 signalCompletion promise pattern (<promise>DONE</promise>)Return value
Stage escalationdirect → heuristic → planned → autonomousN/A
Session persistenceAuto-saves after each iterationManual
ObservabilityBuilt-in event emissionStandard 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.

​
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

CLI Wrapper (praisonai)

13 tools via get_interactive_tools():
  • ACP (4): create/edit/delete files, execute commands
  • LSP (4): symbols, definitions, references, diagnostics
  • Basic (5): read/write files, list, execute, search
Used by: praisonai tui, praisonai "prompt"

Core SDK (praisonaiagents)

3 tools when autonomy=True:
  • ast_grep_search — structural code search
  • ast_grep_rewrite — structural code rewrite
  • ast_grep_scan — pattern scanning
Used by: Agent(autonomy=True) in Python

​
Tools by entry point

Entry PointTools AvailableSource
praisonai tui13 (ACP + LSP + Basic)CLI wrapper
praisonai "prompt"13CLI wrapper
praisonai tracker run30 (expanded set)tracker.py
Agent(autonomy=True) in Python3 (ast-grep only)Core SDK
Agent() in Python0—

​
Design Principles

The current architecture follows a layered separation pattern:
1

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.
2

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.
3

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

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

​
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  # Works with any 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