> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocol Overview

> Understanding the Agent-Client Protocol (ACP) specification

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.

<CardGroup cols={2}>
  <Card title="Standardized" icon="check">
    A single protocol specification that all implementations follow
  </Card>

  <Card title="Bidirectional" icon="arrows-left-right">
    Both agents and clients can send requests to each other
  </Card>

  <Card title="JSON-RPC Based" icon="code">
    Built on the proven JSON-RPC 2.0 specification
  </Card>

  <Card title="Extensible" icon="puzzle-piece">
    Support for custom methods and capabilities
  </Card>
</CardGroup>

## JSON-RPC 2.0 Foundation

ACP is built on top of [JSON-RPC 2.0](https://www.jsonrpc.org/specification), a lightweight remote procedure call protocol. This means all messages follow the JSON-RPC format:

```typescript theme={null}
// 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": { ... }
}
```

<Note>
  JSON-RPC requests include an `id` field and expect a response. Notifications omit the `id` field and don't expect a response.
</Note>

## Protocol Version

The current protocol version is defined in the SDK:

```typescript theme={null}
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):

```typescript theme={null}
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

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Agent
    
    Client->>Agent: initialize (request)
    Agent-->>Client: InitializeResponse
    
    Client->>Agent: session/new (request)
    Agent-->>Client: NewSessionResponse
    
    Client->>Agent: session/prompt (request)
    Agent->>Client: session/update (notification)
    Agent->>Client: session/update (notification)
    Agent-->>Client: PromptResponse
```

## Stream-Based Transport

ACP messages are typically transported as **newline-delimited JSON** (NDJSON) over standard input/output streams:

```typescript theme={null}
// 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:

<CardGroup cols={2}>
  <Card title="Initialization" icon="handshake" href="https://agentclientprotocol.com/protocol/initialization">
    Establishing connections and negotiating capabilities
  </Card>

  <Card title="Sessions" icon="comments" href="/concepts/sessions">
    Managing conversation contexts and state
  </Card>

  <Card title="Prompts" icon="message" href="https://agentclientprotocol.com/protocol/prompt-turn">
    Processing user input and generating responses
  </Card>

  <Card title="Tool Calls" icon="wrench" href="https://agentclientprotocol.com/protocol/tool-calls">
    Executing operations with permission management
  </Card>
</CardGroup>

## Key Features

### Capability Negotiation

During initialization, both sides advertise their capabilities:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```typescript theme={null}
const response = await connection.requestPermission({
  sessionId,
  toolCallId,
  options: [
    { id: "allow", kind: "allow", label: "Allow" },
    { id: "deny", kind: "deny", label: "Deny" }
  ]
});
```

## Learn More

<CardGroup cols={2}>
  <Card title="Full Specification" icon="book" href="https://agentclientprotocol.com">
    Read the complete ACP specification
  </Card>

  <Card title="Agents and Clients" icon="users" href="/concepts/agents-and-clients">
    Understand the two sides of the protocol
  </Card>

  <Card title="Connections" icon="link" href="/concepts/connections">
    Learn how to establish connections
  </Card>

  <Card title="Sessions" icon="comments" href="/concepts/sessions">
    Explore session lifecycle and management
  </Card>
</CardGroup>

<Info>
  For implementation examples, see the [Quickstart Guide](/quickstart) and [Examples](/examples/agent) sections.
</Info>