Skip to main content

​
Agent Client Protocol (ACP)

The Agent Client Protocol (ACP) enables IDEs and code editors to communicate with PraisonAI agents using a standardized JSON-RPC 2.0 protocol over stdio.

​
Overview

ACP allows editors like Zed, JetBrains IDEs, VSCode, and Toad to seamlessly integrate with PraisonAI’s AI coding capabilities.

Quick Start

Get started in 30 seconds

Editor Setup

Configure your IDE

CLI Reference

All command options

Python API

Embed in your app

​
Installation

pip install praisonai[acp]

​
Quick Start

Start the ACP server: 
praisonai acp
That’s it! The server listens on stdin/stdout for JSON-RPC messages.

​
With Options

# Enable debug logging (to stderr)
praisonai acp --debug

# Allow file writes
praisonai acp --allow-write

# Use a specific model
praisonai acp -m gpt-4o

# Resume last session
praisonai acp --resume --last

​
Editor Configuration

​
Zed

Add to ~/.config/zed/settings.json: 
{
  "agent_servers": {
    "PraisonAI": {
      "command": "praisonai",
      "args": ["acp"],
      "env": {}
    }
  }
}

​
JetBrains (IntelliJ, PyCharm, WebStorm)

Add to ~/.jetbrains/acp.json: 
{
  "agent_servers": {
    "PraisonAI": {
      "command": "praisonai",
      "args": ["acp"],
      "env": {}
    }
  }
}

​
Toad

toad acp "praisonai acp"

​
VSCode

The ACP extension auto-discovers agents via PATH. Ensure praisonai is in your PATH: 
which praisonai

​
CLI Reference

praisonai acp [OPTIONS]
OptionDescription
-w, --workspace PATHWorkspace root directory (default: current)
-a, --agent NAMEAgent name or config file
--agents FILEMulti-agent YAML configuration
--routerEnable router agent for task delegation
-m, --model NAMELLM model to use
-r, --resume [ID]Resume session by ID
--lastResume the last session
--approve MODEApproval mode: manual, auto, scoped
--read-onlyRead-only mode (default: enabled)
--allow-writeAllow file write operations
--allow-shellAllow shell command execution
--allow-networkAllow network requests
--debugEnable debug logging to stderr
--profile NAMEUse named profile from config

​
Python API

For advanced users who want to embed ACP in their applications: 
from praisonai.acp import serve

# Start ACP server
serve(
    workspace=".",
    agent="default",
    model="gpt-4o-mini",
    debug=True,
    allow_write=True,
    approval_mode="manual",
)

​
Custom Agent

from praisonai.acp import ACPServer, ACPConfig
from praisonaiagents import Agent

# Create custom agent
agent = Agent(
    name="CodeAssistant",
    instructions="You are an expert coding assistant.",
    model="gpt-4o",
)

# Create ACP server with custom agent
config = ACPConfig(
    workspace=".",
    debug=True,
    allow_write=True,
)
server = ACPServer(config=config, agent=agent)

​
Session Management

​
Resume Sessions

ACP supports session persistence for continuing conversations: 
# Resume by session ID
praisonai acp --resume sess_abc123

# Resume the most recent session
praisonai acp --resume --last

​
Session Storage

Sessions are stored in ~/.praison/acp/sessions/ as JSON files.

​
Permission Model

ACP is safe by default:
PermissionDefaultFlag to Enable
File Read✅ Allowed-
File Write❌ Denied--allow-write
Shell Commands❌ Denied--allow-shell
Network Requests❌ Denied--allow-network

​
Workspace Boundaries

By default, file operations are restricted to:
  • The workspace directory and subdirectories
  • ~/.praison/ configuration directory

​
Protocol Details

ACP uses JSON-RPC 2.0 over stdio:
  • stdin: Receives JSON-RPC requests from the client
  • stdout: Sends JSON-RPC responses (never polluted with logs)
  • stderr: Debug and log output

​
Supported Methods

Agent Methods (client → agent):
MethodDescription
initializeNegotiate protocol version and capabilities
authenticateOptional authentication
session/newCreate a new session
session/loadLoad an existing session
session/promptSend user message
session/cancelCancel ongoing operations
session/set_modeChange operating mode
Client Methods (agent → client):
MethodDescription
session/updateSend progress updates
session/request_permissionRequest user approval
fs/read_text_fileRead file contents
fs/write_text_fileWrite file contents

​
Interactive Mode + ACP

ACP and Interactive Mode are designed to work together without conflicts:

​
Side-by-Side Usage

Run ACP in one terminal while using Interactive Mode in another: 
# Terminal 1: ACP server for IDE
praisonai acp --debug

# Terminal 2: Interactive mode for CLI
praisonai --interactive
Both share the same configuration and credentials from ~/.praison/.

​
Key Points

  • ACP imports don’t affect Interactive Mode performance
  • Both modes use the same session storage (but different sessions)
  • Configuration and API keys are shared safely
  • No stdout contamination between modes

​
Troubleshooting

​
Debug Logging

Enable debug logging to see what’s happening: 
praisonai acp --debug 2>acp.log
Logs go to stderr, so redirect to a file for inspection.

​
Common Issues

“agent-client-protocol package not installed” 
pip install praisonai[acp]
# or
pip install agent-client-protocol
“Session not found” The session may have expired or been deleted. Start a new session or check ~/.praison/acp/sessions/. Editor not connecting
  1. Verify praisonai is in PATH: which praisonai
  2. Test manually: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | praisonai acp
  3. Check editor logs for connection errors

​
Environment Variables

VariableDescription
OPENAI_API_KEYOpenAI API key
ANTHROPIC_API_KEYAnthropic API key
PRAISONAI_WORKSPACEDefault workspace
PRAISONAI_MODELDefault model
PRAISONAI_DEBUGEnable debug mode (true/false)

​
Next Steps

Models

Configure different LLM providers

Tools

Add custom tools to your agent