Agent-Centric Tools Module

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())

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

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

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

​Overview

​Installation

​Quick Start

​Available Tools

​ACP-Powered File Tools

​LSP-Powered Code Intelligence

​Read-Only Tools

​Tool Details

​acp_create_file

​lsp_list_symbols

​Approval Modes

​Architecture

​Operational Notes

​Performance

​Dependencies

​Production Caveats

​Related