Autonomy vs Interactive

Understand how autonomy and interactive modes differ, their tool systems, and the recommended architecture

PraisonAI provides two primary execution approaches: Autonomy (agent-driven results) and Interactive (human-driven sessions). Understanding the distinction between Iterative (autonomous loop) and Interactive (manual loop) is key to building complex workflows.

At a Glance: Iterative vs. Interactive

While the names sound similar, they represent the two sides of “who drives the loop”:

Execution Mode

AutonomyConfig has a mode field that controls execution behavior:

Execution Flow Comparison

Caller Mode (default for autonomy=True)

Iterative Mode (default for full_auto)

When mode="iterative", 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:

Feature Comparison

Speed Profile

Init Overhead (one-time)

Per-Iteration Overhead

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

Important Behavioral Differences

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

Built-in ToolProfiles

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

Tools by entry point

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

When to Use Each Mode

agent = Agent(
    instructions="Help with coding"
)
agent.start("Explain this function")

agent = Agent(
    instructions="You are a research assistant",
    autonomy=True
)
result = agent.start("Search and save to file")
print(result.success)

agent = Agent(
    instructions="Build and test features",
    autonomy={"mode": "iterative"}
)
result = agent.start("Refactor the auth module")
print(result.iterations)

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
)

Related