> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} pip install praisonai ``` ## Quick Start ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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](https://github.com/MervinPraison/PraisonAI/pull/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. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant User participant Agent participant Tool as ACP / LSP Tool participant Bridge as _run_sync User->>Agent: "Edit hello.py" Agent->>Tool: acp_edit_file(...) Tool->>Bridge: submit coroutine Note over Bridge: PRAISONAI_RUN_SYNC_TIMEOUT
default 300 s alt within budget Bridge-->>Tool: result Tool-->>Agent: patch applied Agent-->>User: done else timeout exceeded Bridge-->>Tool: TimeoutError (returns promptly) Tool-->>Agent: tool call failed Agent-->>User: timed out end ``` Override the default five-minute cap by setting the env var before creating the tools: ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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](/docs/features/async-bridge) for the wrapper-level surface. ## Tool Details ### acp\_create\_file Creates a file through the ACP orchestration pipeline: ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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:** ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "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): ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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:** ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "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 | ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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](/docs/cli/interactive-runtime) - Runtime configuration * [Debug CLI](/docs/cli/debug-cli) - Debug commands for LSP/ACP * [ACP](/docs/cli/acp) - Agent Communication Protocol