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.

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]

Option	Description
-w, --workspace PATH	Workspace root directory (default: current)
-a, --agent NAME	Agent name or config file
--agents FILE	Multi-agent YAML configuration
--router	Enable router agent for task delegation
-m, --model NAME	LLM model to use
-r, --resume [ID]	Resume session by ID
--last	Resume the last session
--approve MODE	Approval mode: manual, auto, scoped
--read-only	Read-only mode (default: enabled)
--allow-write	Allow file write operations
--allow-shell	Allow shell command execution
--allow-network	Allow network requests
--debug	Enable debug logging to stderr
--profile NAME	Use 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 ~/.praisonai/acp/sessions/ as JSON files.

Permission Model

ACP is safe by default:

Permission	Default	Flag 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
• ~/.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):

Method	Description
initialize	Negotiate protocol version and capabilities
authenticate	Optional authentication
session/new	Create a new session
session/load	Load an existing session
session/prompt	Send user message
session/cancel	Cancel ongoing operations
session/set_mode	Change operating mode

Client Methods (agent → client):

Method	Description
session/update	Send progress updates
session/request_permission	Request user approval
fs/read_text_file	Read file contents
fs/write_text_file	Write 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 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

Variable	Description
OPENAI_API_KEY	OpenAI API key
ANTHROPIC_API_KEY	Anthropic API key
PRAISONAI_WORKSPACE	Default workspace
PRAISONAI_MODEL	Default model
PRAISONAI_DEBUG	Enable debug mode (true/false)

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

Stay read-only by default

ACP denies writes, shell, and network by default. Add --allow-write, --allow-shell, or --allow-network only when you need them.

Keep stdout clean

Never print to stdout in custom agents — it carries JSON-RPC. Send logs to stderr with --debug 2>acp.log.

Scope the workspace

Set -w/--workspace to the project root so file operations stay inside the intended directory.

Use manual approval for risky actions

Run with --approve manual so each file write or shell command is confirmed before it runs.

Related

Models

Configure different LLM providers.

Tools

Add custom tools to your agent.