Skip to main content
The Agent-Client Protocol (ACP) is a standardized communication protocol that enables AI coding agents to interact with code editors and development environments.

​
What is ACP?

ACP defines a structured way for agents (AI assistants that write and modify code) to communicate with clients (code editors like VS Code, Cursor, or Windsurf). The protocol ensures interoperability, allowing any ACP-compliant agent to work with any ACP-compliant client.

Standardized

A single protocol specification that all implementations follow

Bidirectional

Both agents and clients can send requests to each other

JSON-RPC Based

Built on the proven JSON-RPC 2.0 specification

Extensible

Support for custom methods and capabilities

​
JSON-RPC 2.0 Foundation

ACP is built on top of JSON-RPC 2.0, a lightweight remote procedure call protocol. This means all messages follow the JSON-RPC format: 
// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": { ... }
}

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

// Notification (no response expected)
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": { ... }
}
JSON-RPC requests include an id field and expect a response. Notifications omit the id field and don’t expect a response.

​
Protocol Version

The current protocol version is defined in the SDK: 
import { PROTOCOL_VERSION } from "@anoma/acp-sdk";

console.log(PROTOCOL_VERSION); // 1
During initialization, clients and agents negotiate which protocol version to use. Both parties should support the same major version for compatibility.

​
Communication Model

ACP uses bidirectional communication over a stream-based transport (typically stdio): 
import { AgentSideConnection, ndJsonStream } from "@anoma/acp-sdk";

// Create a stream from stdin/stdout
const stream = ndJsonStream(
  Deno.stdout.writable,
  Deno.stdin.readable
);

// Establish the connection
const connection = new AgentSideConnection(
  (conn) => myAgentImplementation,
  stream
);

​
Message Flow

Both agents and clients can:
  • Send requests and receive responses
  • Send notifications without expecting responses
  • Handle incoming requests from the other side
  • Receive notifications from the other side

​
Stream-Based Transport

ACP messages are typically transported as newline-delimited JSON (NDJSON) over standard input/output streams: 
// Each message is a single line of JSON
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}\n
{"jsonrpc":"2.0","id":1,"result":{...}}\n
{"jsonrpc":"2.0","method":"session/update","params":{...}}\n
The SDK handles this serialization automatically through the ndJsonStream function.

​
Protocol Structure

The protocol is organized around several core concepts:

Initialization

Establishing connections and negotiating capabilities

Sessions

Managing conversation contexts and state

Prompts

Processing user input and generating responses

Tool Calls

Executing operations with permission management

​
Key Features

​
Capability Negotiation

During initialization, both sides advertise their capabilities: 
const initResponse = await connection.initialize({
  protocolVersion: PROTOCOL_VERSION,
  capabilities: {
    fs: { readTextFile: true, writeTextFile: true },
    terminal: true
  },
  clientInfo: {
    name: "My Editor",
    version: "1.0.0"
  }
});

​
Session Management

Sessions represent independent conversation contexts:
  • Create new sessions with session/new
  • Load existing sessions with session/load
  • Fork sessions for parallel exploration
  • Resume sessions without replaying history

​
Real-time Updates

Agents stream progress updates to clients: 
// Agent sends notifications as work progresses
await connection.sessionUpdate({
  sessionId,
  content: {
    type: "text",
    text: "Let me help you with that..."
  }
});

​
Permission System

Agents request permission before sensitive operations: 
const response = await connection.requestPermission({
  sessionId,
  toolCallId,
  options: [
    { id: "allow", kind: "allow", label: "Allow" },
    { id: "deny", kind: "deny", label: "Deny" }
  ]
});

​
Learn More

Full Specification

Read the complete ACP specification

Agents and Clients

Understand the two sides of the protocol

Connections

Learn how to establish connections

Sessions

Explore session lifecycle and management
For implementation examples, see the Quickstart Guide and Examples sections.

Build docs developers (and LLMs) love

Get started for freeTalk to us