Building an ACP-Compatible Agent Live — Bennet Fenner, Zed

The presentation introduces the Agent Client Protocol (ACP), an open-source, JSON RPC-based protocol developed by Zed to enable interoperability between various AI coding agents and client environments. Inspired by Language Server Protocol (LSP), ACP aims to provide a unified interface, allowing users to bring their agent of choice to any compatible editor. It currently sees adoption from agents like OpenCode and Cursor, and clients including OpenClaw, JetBrains, and Obsidian.

A minimal coding agent, not yet ACP-compatible, typically comprises two core tools: read file and edit file (requiring a path, old text, and new text for replacement). The agent operates through an “agent loop” where stateless model APIs (e.g., Anthropic API) are invoked with conversation history. The model’s response can either be an “end turn” (outputting text) or a “tool call.” In the latter case, the agent executes the tool locally, collects the result, and feeds it back to the model, continuing the loop. A handle_tool_call function manages these operations.

To make such an agent ACP-compatible, the agent must implement the ACP agent interface (using, for example, the TypeScript SDK). This involves four key functions:

• initialize: Responds with the supported protocol version and can advertise client/agent capabilities. Authentication is noted as often being handled via environment variables (e.g., API keys).
• new_session: Each new conversation or “thread” in a client triggers a new_session request. The agent generates a unique session ID, instantiates a coding agent associated with the client’s current working directory, stores it internally, and returns the ID to the client.
• prompt: This function receives an array of content blocks (e.g., text, images) and the session ID. It retrieves the correct agent instance, processes the prompt (e.g., ignoring non-text content if not supported), and initiates the agent’s internal tool-calling loop.
• cancel: Supports prompt cancellation.

Real-time interaction with the client is achieved through session updates. Instead of traditional request-response, ACP allows agents to send asynchronous notifications to the client:

• Streaming Model Output: To display tokens as they arrive, the agent sends session_update messages of type AgentMessageChunk. This enables continuous streaming of model responses (e.g., from the Anthropic SDK’s stream.on('text') events) to the client UI.
• Tool Call Visualization: When a tool is invoked (e.g., read file), the agent first sends a session_update of type ToolCall with status in_progress. This update can include metadata like a title or data for client UI (e.g., icons, associated locations). Once the tool call completes, a ToolCallUpdate is sent, updating the status and providing the tool’s content/result.
• Proxied File System Operations: ACP can proxy file system calls through the client (e.g., readTextFile instead of fs.readFile). This is critical for editors, ensuring agents interact with the actual buffer content, including unsaved changes, rather than just the disk state.

The presentation culminated in a live demonstration showcasing the agent’s capabilities: streaming output, visualizing tool calls, and even self-bootstrapping by writing its own code to add a new terminal tool. This new tool leverages client capabilities for managing terminals, allowing the agent to execute shell commands (e.g., sleep 5 ls) and display their output directly in the editor. File edits are communicated as diff content types over ACP, where the agent sends old_text and new_text, and the client handles the visual diffing.

ACP currently operates over standard I/O, with future plans for remote transport. The presenter encourages exploring the protocol at agentclientprotocol.com.

• Tags:
• Tool Calling
• Agent Client Protocol
• ACP
• JSON RPC
• Machine Learning Engineering
• Coding Agent
• AI Code Editor
• Protocol Design
• Zed
• TypeScript SDK