enuno/agent-client-protocol

Agent Client Protocol Skill

The Agent Client Protocol (ACP) is a standardized communication framework between code editors (IDEs) and AI coding agents, similar to how the Language Server Protocol (LSP) unified language server integration. ACP enables any compatible agent to work with any compatible editor without custom integrations.

Core Value Proposition: Build once, run everywhere - agents implementing ACP work with any compatible editor, and editors supporting ACP gain access to all ACP-compatible agents.

When to Use This Skill

This skill should be triggered when:

• Building AI coding agents that need editor integration
• Implementing ACP support in code editors or IDEs
• Creating tool call handlers for agent operations
• Managing file system operations from agents
• Implementing session management for AI assistants
• Building bridges between existing agents and ACP clients
• Understanding JSON-RPC messaging for agent-editor communication

Protocol Overview

The Problem ACP Solves

Before ACP:

• Each editor must build custom integrations for every agent
• Agents must implement editor-specific APIs
• N editors × M agents = N×M integrations needed

After ACP:

• One protocol specification
• N + M implementations needed
• Any agent works with any editor

Deployment Models

┌─────────────────────────────────────────────────────────────┐
│                    LOCAL DEPLOYMENT                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌──────────┐  JSON-RPC/stdio  ┌──────────────────────┐   │
│   │  Editor  │◄────────────────►│  Agent (subprocess)  │   │
│   │  (Zed)   │                  │  (Claude Code)       │   │
│   └──────────┘                  └──────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                   REMOTE DEPLOYMENT                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌──────────┐  HTTP/WebSocket  ┌──────────────────────┐   │
│   │  Editor  │◄────────────────►│  Cloud Agent         │   │
│   │          │                  │  (remote server)     │   │
│   └──────────┘                  └──────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Supported Ecosystem

Compatible Agents (18+)

| Agent | Description | |-------|-------------| | Claude Code | Anthropic's coding agent (via Zed adapter) | | Gemini CLI | Google's AI coding assistant | | Goose | Block's open-source coding agent | | OpenHands | Open-source AI software engineer | | Codex CLI | OpenAI's coding agent (via adapter) | | Augment Code | AI pair programming | | Blackbox AI | Code generation agent | | Docker cagent | Containerized agent | | Mistral Vibe | Mistral AI coding assistant | | Qwen Code | Alibaba's coding agent | | JetBrains Junie | JetBrains AI agent (coming soon) | | fast-agent | Lightweight ACP agent | | OpenCode | Open-source coding agent | | Stakpak | Infrastructure agent | | VT Code | Visual coding agent | | AgentPool | Multi-agent pool | | Code Assistant | General coding assistant | | Kimi CLI | Moonshot AI agent |

Compatible Clients/Editors (15+)

| Client | Platform | |--------|----------| | Zed | Native desktop editor | | JetBrains | IntelliJ IDEA, PyCharm, WebStorm, etc. | | Neovim | Via CodeCompanion or avante.nvim | | Emacs | Via agent-shell.el | | Obsidian | Via Agent Client plugin | | marimo notebook | Python notebook | | DeepChat | Chat interface | | DuckDB | Via sidequery extension | | Agmente | iOS client | | AionUi | Web UI | | aizen | CLI client | | Tidewave | Phoenix LiveView | | Toad | Database client | | Web Browser | Via AI SDK provider | | Sidequery | Coming soon |

---

Protocol Architecture

Communication Model

ACP uses JSON-RPC 2.0 with two message types:

// Methods: Request-Response pairs
interface Request {
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: object;
}

interface Response {
  jsonrpc: "2.0";
  id: string | number;
  result?: any;
  error?: { code: number; message: string; data?: any };
}

// Notifications: One-way messages (no response)
interface Notification {
  jsonrpc: "2.0";
  method: string;
  params?: object;
}

Session Lifecycle

┌─────────────────────────────────────────────────────────────┐
│                    SESSION LIFECYCLE                         │
└─────────────────────────────────────────────────────────────┘

1. INITIALIZATION
   Client ──initialize──► Agent
   Client ◄──capabilities── Agent
   Client ──authenticate──► Agent (if required)

2. SESSION SETUP
   Client ──session/new──► Agent (new conversation)
   OR
   Client ──session/load──► Agent (resume existing)

3. PROMPT TURN CYCLE (repeats)
   Client ──session/prompt──► Agent
   Agent ──session/update──► Client (streaming)
   Agent ──request_permission──► Client (if needed)
   Client ◄──response── Agent

4. TERMINATION
   Client ──session/cancel──► Agent (interrupt)
   OR
   Connection closes

Core Methods

Agent-Side Methods (Required)

| Method | Purpose | |--------|---------| | initialize | Negotiate protocol version and capabilities | | authenticate | Validate client credentials | | session/new | Create new conversation session | | session/prompt | Process user input |

Client-Side Methods

| Method | Purpose | |--------|---------| | session/request_permission | Get user authorization for tool execution | | fs/read_text_file | Read file contents | | fs/write_text_file | Write/create files |

---

Content Types

ACP defines structured content blocks for data exchange:

Text Content

{
  "type": "text",
  "text": "Hello, I can help you with your code."
}

Image Content

{
  "type": "image",
  "mimeType": "image/png",
  "data": "base64encodeddata..."
}

Audio Content

{
  "type": "audio",
  "mimeType": "audio/wav",
  "data": "base64encodedaudio..."
}

Embedded Resource

{
  "type": "resource",
  "resource": {
    "uri": "file:///path/to/file.ts",
    "mimeType": "text/typescript",
    "text": "const x = 1;"
  }
}

Resource Link

{
  "type": "resource_link",
  "uri": "file:///path/to/document.pdf",
  "name": "document.pdf",
  "mimeType": "application/pdf",
  "size": 1024000
}

---

Tool Calls

Creating Tool Calls

Agents report tool invocations via session/update:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "session-123",
    "update": {
      "type": "tool_call",
      "toolCallId": "tc-456",
      "title": "Reading configuration file",
      "kind": "read",
      "status": "pending"
    }
  }
}

Tool Call Kinds

| Kind | Description | |------|-------------| | read | Reading files or data | | edit | Modifying existing content | | delete | Removing files/resources | | move | Moving/renaming files | | search | Searching codebase | | execute | Running commands | | think | Agent reasoning | | fetch | HTTP requests | | other | Custom operations |

Tool Call Status Lifecycle

pending ──► in_progress ──► completed
                  │
                  └──► failed

Permission Requests

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/request_permission",
  "params": {
    "sessionId": "session-123",
    "toolCallId": "tc-456",
    "options": [
      { "label": "Allow", "action": "allow" },
      { "label": "Always Allow", "action": "allow_always" },
      { "label": "Deny", "action": "deny" }
    ]
  }
}

---

File System Operations

Reading Files

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "fs/read_text_file",
  "params": {
    "sessionId": "session-123",
    "path": "/absolute/path/to/file.ts",
    "line": 1,
    "limit": 100
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "const x = 1;\nconst y = 2;\n..."
  }
}

Writing Files

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "fs/write_text_file",
  "params": {
    "sessionId": "session-123",
    "path": "/absolute/path/to/newfile.ts",
    "content": "export const config = {};"
  }
}

// Response (success)
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": null
}

Important Constraints

• All file paths MUST be absolute
• Line numbering is 1-based
• No edit-in-place operations (full read/write only)
• Check clientCapabilities.fs before using

---

Session Modes

Agents can operate in different modes affecting behavior:

Example Modes

| Mode | Description | |------|-------------| | Ask | Request permission before any changes | | Architect | Design and plan without implementation | | Code | Full tool access for code modifications |

Switching Modes

Client-initiated:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/set_mode",
  "params": {
    "sessionId": "session-123",
    "modeId": "code"
  }
}

Agent-initiated (notification):

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "session-123",
    "update": {
      "type": "current_mode_update",
      "modeId": "architect"
    }
  }
}

---

SDK Installation

TypeScript

npm install @agentclientprotocol/sdk

import { AgentSideConnection, ClientSideConnection } from '@agentclientprotocol/sdk';

// For building an agent
const agentConnection = new AgentSideConnection();

// For building a client
const clientConnection = new ClientSideConnection();

API Reference: https://agentclientprotocol.github.io/typescript-sdk

Python

pip install agent-client-protocol
# or with uv
uv add agent-client-protocol

from agent_client_protocol import AgentConnection, ClientConnection

# For building an agent
agent = AgentConnection()

# For building a client
client = ClientConnection()

API Reference: https://agentclientprotocol.github.io/python-sdk

Rust

cargo add agent-client-protocol

Crates.io: https://crates.io/crates/agent-client-protocol

Kotlin

Available via Maven for JVM environments with samples included.

---

Building an ACP Agent

Minimal TypeScript Agent

import { AgentSideConnection } from '@agentclientprotocol/sdk';

const agent = new AgentSideConnection();

// Handle initialization
agent.on('initialize', async (params) => {
  return {
    protocolVersion: '1.0.0',
    capabilities: {
      modes: {
        currentModeId: 'code',
        availableModes: [
          { id: 'code', name: 'Code', description: 'Full coding mode' }
        ]
      }
    }
  };
});

// Handle new sessions
agent.on('session/new', async (params) => {
  return {
    sessionId: crypto.randomUUID(),
    modes: {
      currentModeId: 'code',
      availableModes: [{ id: 'code', name: 'Code' }]
    }
  };
});

// Handle prompts
agent.on('session/prompt', async (params) => {
  const { sessionId, prompt } = params;

  // Stream updates to client
  agent.notify('session/update', {
    sessionId,
    update: {
      type: 'text_delta',
      delta: 'Processing your request...'
    }
  });

  // Process prompt with your LLM
  const response = await processWithLLM(prompt);

  return {
    stopReason: 'endTurn',
    content: [{ type: 'text', text: response }]
  };
});

// Start listening on stdio
agent.listen();

Production Example

See the Gemini CLI implementation for a complete, production-ready ACP agent.

---

MCP Integration

ACP integrates with Model Context Protocol (MCP) in three ways:

1. External MCP Servers

Editors pass user-configured MCP server configs to agents:

{
  "mcpServers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  ]
}

2. Editor-Exported Tools

Editors expose their own MCP server to agents:

{
  "editorMcpServer": {
    "transport": "stdio",
    "capabilities": ["search", "diagnostics", "refactor"]
  }
}

3. Proxy Tunneling

For stdio-only MCP support, editors provide proxies routing requests:

Agent ──MCP request──► Editor Proxy ──MCP──► External Server

---

Design Principles

MCP-Friendly

• Built on JSON-RPC 2.0
• Reuses MCP content types
• Compatible data representations

UX-First

• Balances rendering flexibility
• Appropriate abstraction levels
• Supports diffs, terminal output, file locations

Trusted

• Operates in trusted editor context
• User controls tool execution
• Agents access files and MCP servers

---

Best Practices

For Agent Developers

1. Implement all baseline methods: initialize, authenticate, session/new, session/prompt
2. Stream updates frequently: Use session/update for progress visibility
3. Request permissions appropriately: Use request_permission for destructive operations
4. Handle cancellation: Respect session/cancel notifications
5. Use absolute paths: All file operations require absolute paths

For Client Developers

1. Declare capabilities accurately: Only advertise supported features
2. Handle streaming updates: Process session/update notifications in real-time
3. Implement permission UI: Show user-friendly permission dialogs
4. Support multiple sessions: Allow concurrent agent sessions

Security Considerations

• Validate all file paths (prevent directory traversal)
• Implement rate limiting for tool calls
• Sanitize user input before passing to agents
• Log all operations for audit trails

---

Error Handling

JSON-RPC Error Codes

| Code | Meaning | |------|---------| | -32700 | Parse error | | -32600 | Invalid request | | -32601 | Method not found | | -32602 | Invalid params | | -32603 | Internal error |

Error Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": { "method": "unknown/method" }
  }
}

---

Resources

Official Documentation

• ACP Website
• Protocol Schema

SDKs

• TypeScript SDK
• Python SDK
• Rust Crate

Examples

• Gemini CLI Integration
• Goose Agent

Community

• Zed ACP Documentation
• JetBrains AI Assistant ACP

---

Version History

• 1.0.0 (2026-01-10): Initial skill release
  • Complete protocol overview
  • Session lifecycle documentation
  • Tool call and permission handling
  • File system operations
  • Session modes
  • SDK installation guides (TypeScript, Python, Rust, Kotlin)
  • 18 supported agents, 15 supported clients
  • MCP integration patterns
  • Best practices and error handling