OpenACP/docs/acp-guide.md
0xmrpeter 82f62ef434 Update ACP documentation to English and improve clarity
- Enhanced clarity in explanations regarding the Agent Client Protocol (ACP) and its architecture.
- Updated section headings and content to reflect the new language and improve readability.
2026-03-20 13:09:24 +07:00

13 KiB
Raw Permalink Blame History

Agent Client Protocol (ACP) — Reference Documentation

Protocol version: v0.11.3 (March 2026) Source: agentclientprotocol.com | GitHub: agentclientprotocol/agent-client-protocol


1. What is ACP?

Agent Client Protocol (ACP) is a protocol that standardizes communication between code editors/IDEs (Client) and AI coding agents (Agent). Inspired by Language Server Protocol (LSP) — which standardized autocomplete, go-to-definition, etc. for all editors — ACP does the same for AI coding agents.

Before ACP: Each agent-editor pair needed its own custom integration → N agents × M editors = N×M integrations.

After ACP: An agent implements ACP once → works on every editor that supports ACP. An editor implements ACP once → works with every agent that supports ACP.

2. Why is ACP needed?

ACP solves 3 main problems:

  • Integration overhead: Each new agent-editor combo requires custom work. With ACP, implement once and you're done.
  • Limited compatibility: Agents only work on certain editors. ACP breaks this limitation.
  • Developer lock-in: Choosing agent A means being forced to use editor X. ACP allows free combination.

Relationship with MCP: MCP (Model Context Protocol) handles what — what data and tools the agent accesses. ACP handles where — where the agent lives in the developer's workflow. The two protocols complement each other.

3. Architecture Overview

┌─────────────────────────────────────────────────┐
│                   USER (Developer)               │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              CLIENT (Code Editor/IDE)            │
│                                                  │
│  - Sends user prompts to the Agent              │
│  - Renders responses (text, diff, tool calls)   │
│  - Manages permissions for tool execution       │
│  - Provides filesystem access                   │
│  - Exposes MCP servers to the Agent             │
└──────────────────────┬──────────────────────────┘
                       │  JSON-RPC
                       │  (stdio / HTTP / WebSocket)
┌──────────────────────▼──────────────────────────┐
│                 AGENT (AI Coding Agent)           │
│                                                  │
│  - Receives prompts, calls LLM                  │
│  - Executes tool calls (edit file, run cmd...)  │
│  - Sends realtime updates to Client             │
│  - Connects to MCP servers for context          │
└─────────────────────────────────────────────────┘

3.1 Transport Layer

Mode Transport Use case
Local JSON-RPC over stdio Agent runs as a subprocess of the editor
Remote HTTP or WebSocket Agent runs on a separate cloud/server

Local mode is the most common currently. The editor launches the agent process and communicates via stdin/stdout. A single connection can manage multiple sessions simultaneously.

Remote mode is being further developed, suitable for enterprise deployment or shared agent infrastructure.

3.2 Trust Model

ACP works best when the editor communicates with a trusted agent. The user still retains control:

  • Approve/reject tool execution
  • Control filesystem access
  • Manage MCP server configurations

4. Detailed Protocol Flow

4.1 Initialization (Handshake)

When the editor connects to the agent, the initialization process occurs:

Client                              Agent
  │                                   │
  │──── initialize ──────────────────►│
  │     {                             │
  │       protocolVersion: 1,         │
  │       clientCapabilities: {...},  │
  │       name: "my-editor",         │
  │       version: "1.0"             │
  │     }                             │
  │                                   │
  │◄──── initialize response ────────│
  │     {                             │
  │       protocolVersion: 1,         │
  │       agentCapabilities: {...},   │
  │       name: "my-agent",          │
  │       version: "2.0"             │
  │     }                             │
  │                                   │

Client Capabilities (declared by the editor):

  • fileSystem.readTextFile — allows the agent to read files
  • fileSystem.writeTextFile — allows the agent to write files
  • terminal — allows the agent to run shell commands

Agent Capabilities (declared by the agent):

  • loadSession — supports reloading previous sessions
  • promptCapabilities — supported content types: Image, Audio, embedded context
  • mcp — supports HTTP/SSE transport for MCP
  • Session methods — supported operations (list, fork, configure...)

Version Negotiation: Protocol version is an integer (MAJOR version). If there's a mismatch, the agent returns the highest version it supports. The client should close the connection if incompatible.

4.2 Prompt Turn (Main Loop)

This is the core interaction cycle. Each prompt turn consists of 6 steps:

Client                              Agent                    LLM
  │                                   │                       │
  │─── session/prompt ──────────────►│                       │
  │    { user message + resources }   │                       │
  │                                   │─── forward prompt ──►│
  │                                   │                       │
  │                                   │◄── response ─────────│
  │                                   │    (text + tool calls)│
  │◄── session/update (notification)─│                       │
  │    { plan, text, tool calls }     │                       │
  │                                   │                       │
  │    [If there's a tool call]       │                       │
  │◄── permission request ───────────│                       │
  │──── permission response ────────►│                       │
  │                                   │── execute tool ──────►│
  │◄── session/update (tool status)──│                       │
  │    { in_progress / completed }    │                       │
  │                                   │                       │
  │    [Tool result → LLM → loop]     │                       │
  │                                   │                       │
  │◄── session/prompt response ──────│                       │
  │    { StopReason }                 │                       │

Stop Reasons:

  • end_turn — Completed normally
  • max_tokens — Token limit reached
  • max_turn_requests — Exceeded maximum model call count
  • refusal — Agent refused to continue
  • cancelled — Client cancelled the turn

4.3 Session Management

session/new        → Create a new session
session/prompt     → Send a prompt
session/update     → Agent sends update (notification)
session/cancel     → Cancel processing
session/list       → List sessions
session/load       → Reload a previous session
session/fork       → Fork a session (branching)
session/configure  → Configure a session

5. MCP Integration

ACP integrates tightly with MCP:

  • The editor passes MCP server configs to the Agent during initialization
  • The agent connects directly to MCP servers
  • When the editor exposes tools via MCP, it deploys a proxy tunnel — routing requests back to the editor
  • Supports both stdio-based and HTTP/SSE MCP transport
Editor ──(ACP)──► Agent ──(MCP)──► MCP Server (DB, API, tools...)
  │                                      ▲
  └──── proxy tunnel (for editor tools)──┘

6. Current Ecosystem

6.1 Editors supporting ACP (Clients)

  • Zed — Native ACP support
  • JetBrains IDEs — Via AI Assistant plugin
  • Neovim — Community plugin
  • Marimo — Notebook editor
  • Cursor — ACP documentation available

6.2 Agents supporting ACP (40+)

  • Claude Code (Anthropic)
  • Codex CLI (OpenAI)
  • Gemini (Google)
  • Goose (Block)
  • GitHub Copilot (public preview since Jan 2026)
  • Cline, OpenHands, Factory Droid, Docker cagent
  • And many more...

6.3 Official SDKs

Language Package Registry
Rust agent-client-protocol crates.io
TypeScript @agentclientprotocol/sdk npm
Python python-sdk PyPI
Java java-sdk Maven
Kotlin acp-kotlin Maven (JVM)

7. Approaches for Building Products

7.1 Build a New Agent

If you want to create your own AI coding agent:

Approach:

  1. Choose an appropriate SDK (TypeScript or Python are most common)
  2. Implement the ACP protocol: initialize handshake, prompt turn loop, session management
  3. Connect an LLM backend (OpenAI, Anthropic, local model...)
  4. Implement tool execution (file edit, terminal, search...)
  5. The agent automatically becomes compatible with all ACP-supporting editors

Example use cases:

  • An agent specialized for a specific language/framework
  • An agent integrated with company-specific tools (CI/CD, internal APIs)
  • An agent with specialized reasoning (security audit, performance optimization)

7.2 Build a New Editor/Client

If you want to create an IDE or coding tool:

Approach:

  1. Implement the ACP client protocol
  2. Support local agent launch (subprocess + stdio)
  3. Render agent output (markdown text, diffs, tool status)
  4. Implement permission UI for tool execution
  5. Automatically compatible with all ACP agents

7.3 Build an Agent Platform / Registry

Idea: A marketplace or registry where developers discover, install, and manage ACP agents.

Reference: ACP already has a Registry concept — you can build on that or create your own curated experience.

7.4 Build Enterprise Agent Infrastructure

Idea: Remote ACP agent hosting for teams/enterprises:

  • Shared agent instances on a server
  • Centralized MCP server management
  • Usage tracking, audit logs
  • Custom tool permissions per team/role

7.5 Build an Agent Development Framework

Idea: A framework that makes it easy for developers to build ACP agents:

  • Boilerplate handling (protocol, session management)
  • Plugin system for tools
  • Testing utilities
  • Deployment tools (local + remote)

7.6 Bridge ACP with Non-Coding Domains

ACP currently focuses on coding, but this pattern can be applied to:

  • Document editing agents
  • Design tool agents
  • Data analysis agents
  • DevOps/infrastructure agents

8. Technical Notes for Implementation

8.1 JSON-RPC Basics

ACP uses JSON-RPC 2.0. Each message has the following format:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": { ... }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

// Notification (no id, no response expected)
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": { ... }
}

8.2 Content Types

Text defaults to Markdown. Additionally supports:

  • Image content
  • Audio content
  • Embedded context (file references)

8.3 MCP Type Reuse

ACP reuses JSON structures from MCP when possible, but adds custom types for coding-specific features like diff display.

8.4 Feature Flags

The protocol uses feature flags to indicate features under development. Check agent capabilities in the initialize response.

9. Resources

10. Quick Summary

Concept Explanation
ACP Protocol standardizing editor ↔ agent communication
Client Code editor/IDE (Zed, JetBrains, Neovim...)
Agent AI coding tool (Claude Code, Codex, Gemini...)
Transport stdio (local) or HTTP/WebSocket (remote)
Protocol JSON-RPC 2.0
Session A working session between client and agent
Prompt Turn A complete request-response cycle
MCP Complementary protocol — provides data/tools to the agent
SDK Rust, TypeScript, Python, Java, Kotlin
License Apache 2.0