ACP – Agent Client Protocol API

Connect IDEs and editors to PraisonAI agents via ACP

Expose a PraisonAI Agent to your editor over the Agent Client Protocol with a single command.

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

agent = Agent(name="CodeAssistant", instructions="You are an expert coding assistant.")
server = ACPServer(config=ACPConfig(workspace="."), agent=agent)

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.

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]

Writes enabled by --allow-write are validated by the Safe Edit Pipeline.

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,
    allow_shell=False,
    allow_network=False,     # search / crawl tools — off by default
    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,
    allow_shell=False,
    allow_network=False,
)
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 ~/.praisonai/acp/sessions/ as JSON files.

Permission Model

ACP is safe by default:

Workspace Boundaries

By default, file operations are restricted to:

• The workspace directory and subdirectories
• ~/.praisonai/ 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):

Client Methods (agent → client):

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 chat

Both share the same configuration and credentials from ~/.praisonai/.

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 ~/.praisonai/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

How It Works

The editor speaks JSON-RPC to the ACP server over stdio; the server drives the Agent and streams updates back.

Best Practices

Related