Agent-Centric Tools Module

LSP/ACP-powered tools that make the Agent the central orchestrator for file operations and code intelligence

Overview

The Agent-Centric Tools module provides tools that route file operations and code intelligence through LSP (Language Server Protocol) and ACP (Agent Communication Protocol), making the Agent the central orchestrator for all actions.

This ensures:

• Plan → Approve → Apply → Verify flow for file modifications
• LSP-powered code intelligence with fallback to regex
• Full action tracking via ACP sessions
• Multi-agent safe operations with proper attribution

Installation

The agent-centric tools are included in the praisonai package:

pip install praisonai

Quick Start

import asyncio
from praisonai.cli.features import (
    create_agent_centric_tools,
    InteractiveRuntime,
    RuntimeConfig
)
from praisonaiagents import Agent

async def main():
    # 1. Create runtime with ACP enabled
    config = RuntimeConfig(
        workspace="./my_project",
        lsp_enabled=True,
        acp_enabled=True,
        approval_mode="auto"  # or "manual" or "scoped"
    )
    runtime = InteractiveRuntime(config)
    await runtime.start()
    
    # 2. Create agent-centric tools
    tools = create_agent_centric_tools(runtime)
    
    # 3. Create Agent with LSP/ACP-powered tools
    agent = Agent(
        name="FileAgent",
        instructions="You help create and manage files. Use acp_create_file to create files.",
        tools=tools,
        
    )
    
    # 4. Agent will use ACP for file operations
    result = agent.start("Create a Python file called hello.py with a hello function")
    print(result)
    
    await runtime.stop()

asyncio.run(main())

Both from praisonai.cli.features import create_agent_centric_tools and from praisonai.cli.features.agent_tools import create_agent_centric_tools now resolve to the same implementation (canonical: praisonai_code.cli.features.agent_tools). Older PraisonAI releases briefly had these resolve to two separate copies — upgrade to the latest praisonai release for a single source of truth. See PR #3361.

Available Tools

ACP-Powered File Tools

Tool	Description	Risk Level
acp_create_file	Create file with plan/approve/apply/verify	Medium
acp_edit_file	Edit file with ACP tracking	Medium
acp_delete_file	Delete file (requires approval)	High
acp_execute_command	Execute shell command with tracking	High

LSP-Powered Code Intelligence

Tool	Description	Fallback
lsp_list_symbols	List symbols in file	Regex extraction
lsp_find_definition	Find symbol definition	Grep search
lsp_find_references	Find symbol references	Grep search
lsp_get_diagnostics	Get errors/warnings	N/A

Read-Only Tools

Tool	Description
read_file	Read file content
list_files	List directory contents

Timeouts & Cancellation

Every agent-centric tool call is bounded by PRAISONAI_RUN_SYNC_TIMEOUT (default 300 seconds) so a hung ACP/LSP tool can never block the agent indefinitely.

Override the default five-minute cap by setting the env var before creating the tools:

import os
from praisonai.cli.features import (
    create_agent_centric_tools,
    InteractiveRuntime,
    RuntimeConfig,
)
from praisonaiagents import Agent

os.environ["PRAISONAI_RUN_SYNC_TIMEOUT"] = "30"  # tighten to 30 s for fast-fail

runtime = InteractiveRuntime(RuntimeConfig(workspace="./my_project", acp_enabled=True))
# ... await runtime.start()
tools = create_agent_centric_tools(runtime)

agent = Agent(name="FileAgent", instructions="Edit files with ACP tools.", tools=tools)
agent.start("Add a hello() function to hello.py")

Configuration:

Env var	Type	Default	Description
PRAISONAI_RUN_SYNC_TIMEOUT	float (seconds)	300	Maximum wall-clock time a single agent-centric tool call (acp_*, lsp_*, edit_file, etc.) is allowed before the underlying coroutine is cancelled and TimeoutError is raised.

Behaviour on timeout:

• The coroutine is cancelled (future.cancel()) and concurrent.futures.TimeoutError propagates to the agent.
• The worker pool is shut down with wait=False, so the tool call returns immediately — it does not block until the hung coroutine finishes.
• Because Python threads cannot be force-killed, a hung sync tool may keep running in the background daemon thread; it is reclaimed on interpreter exit. Do not rely on the timeout as a hard security cutoff.

This env var is shared with the wrapper-level praisonai._async_bridge.run_sync. Setting it applies to both the wrapper bridge (used by gateway, a2u, mcp_server, scheduler) and the praisonai-code agent-tool bridge (used by the ACP/LSP tools created above). See Async Bridge for the wrapper-level surface.

Tool Details

acp_create_file

Creates a file through the ACP orchestration pipeline:

def acp_create_file(filepath: str, content: str) -> str:
    """
    Create a file through ACP with plan/approve/apply/verify flow.
    
    Args:
        filepath: Path to the file to create (relative to workspace)
        content: Content to write to the file
        
    Returns:
        JSON string with result including plan status and verification
    """

Example Response:

{
  "success": true,
  "file_created": "hello.py",
  "plan_id": "plan_1767198057_1",
  "status": "verified",
  "verified": true
}

lsp_list_symbols

Lists all symbols in a file using LSP (with regex fallback):

def lsp_list_symbols(file_path: str) -> str:
    """
    List all symbols (functions, classes, methods) in a file using LSP.
    
    Falls back to regex-based extraction if LSP is unavailable.
    
    Args:
        file_path: Path to the file to analyze
        
    Returns:
        JSON string with list of symbols and their locations
    """

Example Response:

{
  "intent": "list_symbols",
  "success": true,
  "lsp_used": false,
  "fallback_used": true,
  "data": [
    {"name": "hello", "kind": "function", "line": 1},
    {"name": "MyClass", "kind": "class", "line": 10}
  ],
  "citations": [{"file": "hello.py", "type": "symbols", "count": 2}]
}

Approval Modes

The approval_mode parameter controls how file modifications are approved:

Mode	Behavior
manual	All modifications require explicit approval
auto	All modifications are auto-approved
scoped	Safe operations auto-approved, dangerous require approval

config = RuntimeConfig(
    workspace="./project",
    acp_enabled=True,
    approval_mode="scoped"  # Auto-approve safe, manual for dangerous
)

Architecture

User Prompt
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  Agent (CENTRAL ORCHESTRATOR)                               │
│                                                             │
│  Tools powered by LSP/ACP:                                 │
│  ├── acp_create_file() → ActionOrchestrator                │
│  ├── acp_edit_file() → ActionOrchestrator                  │
│  ├── lsp_list_symbols() → CodeIntelligenceRouter           │
│  └── lsp_find_definition() → CodeIntelligenceRouter        │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│  ActionOrchestrator                                         │
│  Plan → Approve → Apply → Verify                           │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
File Operations (with ACP tracking + verification)

Operational Notes

Performance

• All imports are lazy-loaded
• LSP client starts only when lsp_enabled=True
• ACP session is lightweight (in-process)

Dependencies

• praisonaiagents - Core agent functionality
• pylsp (optional) - For LSP code intelligence

Production Caveats

• LSP requires language server to be installed (e.g., pylsp for Python)
• If LSP unavailable, falls back to regex-based symbol extraction
• ACP tracking is in-memory; use external storage for persistence

Related

• Interactive Runtime - Runtime configuration
• Debug CLI - Debug commands for LSP/ACP
• ACP - Agent Communication Protocol