Interactive Tools - PraisonAI Documentation

Overview

PraisonAI interactive modes (praisonai tui launch and praison "prompt") now include ACP (Agentic Change Plan) and LSP (Language Server Protocol) tools by default. This enables agents to:

Create, edit, and delete files with plan/approve/apply/verify flow (ACP)
Analyze code with symbol listing, definition lookup, and reference finding (LSP)
Execute commands with safety guardrails

Default Tool Groups

Group	Tools	Description
ACP	`acp_create_file`, `acp_edit_file`, `acp_delete_file`, `acp_execute_command`	Safe file operations with plan/approve/apply
LSP	`lsp_list_symbols`, `lsp_find_definition`, `lsp_find_references`, `lsp_get_diagnostics`	Code intelligence
Basic	`read_file`, `write_file`, `list_files`, `execute_command`, `internet_search`	Standard tools

All groups are enabled by default in interactive modes.

Quick Start

# Run with all default tools (ACP + LSP + Basic)
praison "Create a Python file that calculates fibonacci numbers"

# Launch TUI with all default tools
praisonai tui launch

Disabling Tool Groups

CLI Flags

# Disable ACP tools (no file modification capabilities)
praison "Analyze this code" --no-acp

# Disable LSP tools (no code intelligence)
praison "Write a script" --no-lsp

# Disable both (basic tools only)
praison "Search the web" --no-acp --no-lsp

# TUI with disabled groups
praisonai tui launch --no-acp --no-lsp

Environment Variables

# Disable specific groups via env
export PRAISON_TOOLS_DISABLE=acp,lsp
praison "Hello world"

# Set workspace
export PRAISON_WORKSPACE=/path/to/project

Tool Details

ACP Tools (Agentic Change Plan)

ACP tools route file operations through a plan/approve/apply/verify flow:

User Request → Create Plan → Approve → Apply → Verify

Tool	Description
`acp_create_file`	Create a new file with content
`acp_edit_file`	Edit an existing file
`acp_delete_file`	Delete a file (requires approval)
`acp_execute_command`	Execute a shell command

Safety Features:

All destructive operations require approval
Changes are tracked and can be verified
Workspace boundary enforcement

LSP Tools (Code Intelligence)

LSP tools provide semantic code analysis:

Tool	Description
`lsp_list_symbols`	List functions, classes, methods in a file
`lsp_find_definition`	Find where a symbol is defined
`lsp_find_references`	Find all references to a symbol
`lsp_get_diagnostics`	Get errors and warnings

Fallback Behavior:

If LSP server is unavailable, tools fall back to regex-based extraction
Results include lsp_used flag to indicate which method was used

Basic Tools

Standard file and search tools:

Tool	Description
`read_file`	Read file content
`write_file`	Write content to file
`list_files`	List directory contents
`execute_command`	Run shell commands
`internet_search`	Search the web

Python API

from praisonai.cli.features import (
    get_interactive_tools,
    ToolConfig,
    TOOL_GROUPS,
)

# Get all default tools
tools = get_interactive_tools()

# Get tools with specific config
config = ToolConfig(
    workspace="/path/to/project",
    enable_acp=True,
    enable_lsp=True,
    approval_mode="auto",  # or "manual"
)
tools = get_interactive_tools(config=config)

# Disable specific groups
tools = get_interactive_tools(disable=["acp"])

# Get only specific groups
tools = get_interactive_tools(groups=["basic"])

Configuration

ToolConfig Options

Option	Default	Description
`workspace`	`os.getcwd()`	Working directory
`enable_acp`	`True`	Enable ACP tools
`enable_lsp`	`True`	Enable LSP tools
`enable_basic`	`True`	Enable basic tools
`approval_mode`	`"auto"`	Approval mode: auto, manual, scoped

Approval Modes

Mode	Description
`auto`	Full privileges - all operations auto-approved (default for automation)
`manual`	All write operations require explicit approval
`scoped`	Safe operations auto-approved, dangerous ones (delete, shell) require approval

Important: When approval_mode=auto, write operations work even without ACP subsystem running. This enables seamless automation and testing.

Environment Variables

Variable	Description
`PRAISON_TOOLS_DISABLE`	Comma-separated groups to disable
`PRAISON_WORKSPACE`	Override workspace path
`PRAISON_APPROVAL_MODE`	Set approval mode (auto, manual, scoped)
`PRAISON_DEBUG`	Set to `1` to enable debug logging

Debug Logging

Enable debug logging to troubleshoot tool execution:

# Via CLI flag
praisonai chat --debug

# Via environment variable
export PRAISON_DEBUG=1
praisonai chat

# Via slash command during session
/debug

Debug logs are written to ~/.praisonai/async_tui_debug.log.

Architecture

praison "prompt" / praisonai tui launch
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  get_interactive_tools()                                    │
│  (Canonical source of truth)                               │
└─────────────────────────────────────────────────────────────┘
    │
    ├── ACP Tools → ActionOrchestrator → Plan/Apply/Verify
    │
    ├── LSP Tools → CodeIntelligenceRouter → LSP/Fallback
    │
    └── Basic Tools → Direct execution

Testing ACP/LSP Tools

The interactive test framework allows you to test ACP and LSP tools in isolation with full tracing and assertions.

Tool Tracing

When running tests, all tool calls are captured in a structured trace:

{
  "tool_name": "acp_create_file",
  "args": ["hello.py", "print('hello')"],
  "kwargs": {},
  "result": "{\"success\": true, \"file_created\": \"hello.py\"}",
  "success": true,
  "duration": 0.234,
  "timestamp": "2024-01-15T10:30:00Z"
}

Testing Tool Calls

Use the CSV test runner to verify expected tool usage:

id,name,prompts,expected_tools,forbidden_tools
test_01,Create File,"Create hello.py",acp_create_file,acp_delete_file
test_02,Read Only,"Read the README",read_file,"acp_create_file,acp_edit_file"
test_03,Code Analysis,"List symbols in main.py",lsp_list_symbols,

Tool Assertions

The test harness supports two types of tool assertions:

Expected Tools: Tools that MUST be called

expected_tools,acp_create_file,acp_edit_file

Forbidden Tools: Tools that MUST NOT be called

forbidden_tools,acp_delete_file,acp_execute_command

Running Tool Tests

# Run the tools test suite
praisonai test interactive --suite tools

# Run with verbose output to see tool calls
praisonai test interactive --suite tools --verbose

# Keep artifacts to inspect tool traces
praisonai test interactive --suite tools --keep-artifacts

Inspecting Tool Traces

After running with --keep-artifacts, check the tool_trace.jsonl file:

# View tool trace for a specific test
cat artifacts/test_01/tool_trace.jsonl | jq .

# Count tool calls
wc -l artifacts/test_01/tool_trace.jsonl

# Filter by tool name
grep "acp_create_file" artifacts/test_01/tool_trace.jsonl

Testing LSP Fallback

LSP tools gracefully fall back to regex when LSP server is unavailable:

id,name,prompts,expected_tools,workspace_fixture
lsp_01,List Symbols,"List all functions in utils.py",lsp_list_symbols,python_project
lsp_02,Find Definition,"Where is Calculator defined?",lsp_find_definition,python_project

The test will pass regardless of whether LSP or regex fallback is used, as long as results are returned.

Network-Enabled Testing

For tests that require network access (e.g., GitHub operations), use the PRAISON_LIVE_NETWORK environment variable:

# Enable network operations
PRAISON_LIVE_NETWORK=1 praisonai test interactive --suite github-advanced

Command Allowlist

When PRAISON_LIVE_NETWORK=1 is set, the following commands are allowed:

Category	Commands
Git	`git`
GitHub CLI	`gh`
Python	`python`, `python3`, `pip`, `pip3`, `uv`, `pytest`, `ruff`, `black`, `mypy`
Node	`node`, `npm`, `npx`
Build	`make`
Utilities	`echo`, `cat`, `ls`, `pwd`, `head`, `tail`, `wc`, `grep`, `find`, `mkdir`, `touch`, `cp`, `mv`

Blocked Commands

The following commands are always blocked for safety:

rm -rf /, sudo, su, systemctl, shutdown, reboot, dd, mkfs, fdisk
curl | bash, wget | bash, fork bombs

Secret Redaction

All artifacts automatically redact sensitive information:

GitHub tokens (ghp_*, gho_*, github_pat_*)
OpenAI keys (sk-*, sk-proj-*)
AWS credentials (AKIA*)
Bearer tokens
Passwords and secrets in config

Agent-Centric Tools - ACP/LSP tool implementation
LSP Code Intelligence - LSP details
Debug CLI - Debug commands
Interactive TUI Testing - Test framework

CLI

​Overview

​Default Tool Groups

​Quick Start

​Disabling Tool Groups

​CLI Flags

​Environment Variables

​Tool Details

​ACP Tools (Agentic Change Plan)

​LSP Tools (Code Intelligence)

​Basic Tools

​Python API

​Configuration

​ToolConfig Options

​Approval Modes

​Environment Variables

​Debug Logging

​Architecture

​Testing ACP/LSP Tools

​Tool Tracing

​Testing Tool Calls

​Tool Assertions

​Running Tool Tests

​Inspecting Tool Traces

​Testing LSP Fallback

​Network-Enabled Testing

​Command Allowlist

​Blocked Commands

​Secret Redaction

​Related

Overview

Default Tool Groups

Quick Start

Disabling Tool Groups

CLI Flags

Environment Variables

Tool Details

ACP Tools (Agentic Change Plan)

LSP Tools (Code Intelligence)

Basic Tools

Python API

Configuration

ToolConfig Options

Approval Modes

Environment Variables

Debug Logging

Architecture

Testing ACP/LSP Tools

Tool Tracing

Testing Tool Calls

Tool Assertions

Running Tool Tests

Inspecting Tool Traces

Testing LSP Fallback

Network-Enabled Testing

Command Allowlist

Blocked Commands

Secret Redaction

Related