> ## 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.

# 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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Agent Client Protocol"
        Editor[📋 Editor] --> ACP[🤖 ACP Server]
        ACP --> Agent[🧠 Agent]
        Agent --> Result[✅ Response]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Editor,ACP input
    class Agent process
    class Result output
```

# 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.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="#quick-start">
    Get started in 30 seconds
  </Card>

  <Card title="Editor Setup" icon="code" href="#editor-configuration">
    Configure your IDE
  </Card>

  <Card title="CLI Reference" icon="terminal" href="#cli-reference">
    All command options
  </Card>

  <Card title="Python API" icon="python" href="#python-api">
    Embed in your app
  </Card>
</CardGroup>

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai[acp]
```

## Quick Start

Start the ACP server:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai acp
```

That's it! The server listens on stdin/stdout for JSON-RPC messages.

### With Options

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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`:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "agent_servers": {
    "PraisonAI": {
      "command": "praisonai",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

### JetBrains (IntelliJ, PyCharm, WebStorm)

Add to `~/.jetbrains/acp.json`:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "agent_servers": {
    "PraisonAI": {
      "command": "praisonai",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

### Toad

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
toad acp "praisonai acp"
```

### VSCode

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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"**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Editor
    participant ACP as ACP Server
    participant Agent

    Editor->>ACP: session/prompt (JSON-RPC over stdio)
    ACP->>Agent: Run the prompt in the workspace
    Agent-->>ACP: session/update progress
    ACP-->>Editor: Response + permission requests
```

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Keep stdout clean">
    Never print to stdout in custom agents — it carries JSON-RPC. Send logs to stderr with `--debug 2>acp.log`.
  </Accordion>

  <Accordion title="Scope the workspace">
    Set `-w/--workspace` to the project root so file operations stay inside the intended directory.
  </Accordion>

  <Accordion title="Use manual approval for risky actions">
    Run with `--approve manual` so each file write or shell command is confirmed before it runs.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Models" icon="brain" href="/docs/models">
    Configure different LLM providers.
  </Card>

  <Card title="Tools" icon="wrench" href="/docs/tools">
    Add custom tools to your agent.
  </Card>
</CardGroup>