Building an ACP Agent from Scratch Using Rust

The Situation with ACP and Rust

When I started exploring the Agent Client Protocol for a project where I wanted to build a coding assistant that worked natively in Zed and other ACP-compatible editors, I quickly noticed that the ecosystem is TypeScript/Node.js-first. The official ACP reference implementations — from Codex CLI, Gemini CLI, Cline, and others — are mostly Node.js or Python.

As of early 2026, there is no official Rust SDK for ACP. This article is about implementing it from the protocol specification directly.

The good news: ACP is a clean JSON-RPC 2.0 protocol over stdio. If you've read the spec, the wire format is straightforward. And Rust has everything we need to implement it properly: async I/O, excellent JSON support, and precise control over stdio framing.

This article walks through building a minimal but complete ACP-compliant agent in Rust — one that can negotiate capabilities with an ACP client (like Zed), create sessions, receive prompt turns, and stream back responses.

---

ACP Wire Protocol Recap

Before writing code, it's worth being precise about the protocol. Everything is newline-delimited JSON-RPC 2.0 over stdin/stdout.

Methods the Agent must implement (baseline)

Method	Direction	Description
initialize	Client → Agent	Version negotiation and capability exchange
session/new	Client → Agent	Create a new conversation session
session/prompt	Client → Agent	Send a user message; agent processes and responds

Notifications the Agent sends

Notification	Direction	Description
session/update	Agent → Client	Streaming output: text chunks, tool calls, diffs, thoughts

Methods the Agent can call on the Client

Method	Direction	Description
session/request_permission	Agent → Client	Ask user to approve a tool call

The key distinction from MCP: ACP is bidirectional. The agent makes requests of the editor (for file system access, terminal, permission gating), not just the other way around.

---

What We're Building

A minimal but spec-compliant ACP agent that:

1. Handles initialize — capability negotiation

2. Handles session/new — creates a session with a unique ID

3. Handles session/prompt — receives a user message, sends back streaming session/update notifications, and returns a final response

4. Runs over stdio

The actual AI logic is a placeholder — the focus here is the correct ACP framing and protocol flow.

---

Project Setup

cargo new acp-agent --bin
cd acp-agent

# Cargo.toml
[package]
name = "acp-agent"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
uuid = { version = "1", features = ["v4"] }
anyhow = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

No ACP SDK needed — we implement the protocol directly from the spec.

---

Understanding the Message Framing

ACP uses JSON-RPC 2.0 over stdio with newline delimiters. Each message is a single JSON object followed by \n.

Incoming (from editor/client):

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{...}}\n
{"jsonrpc":"2.0","id":1,"method":"session/new","params":{...}}\n
{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{...}}\n

Outgoing (from agent/us):

• Responses (reply to a request, must include the same id):

{"jsonrpc":"2.0","id":0,"result":{...}}\n

• Notifications (no id field, no response expected):

{"jsonrpc":"2.0","method":"session/update","params":{...}}\n

---

Implementation

Step 1: Define the JSON-RPC Message Types

// src/jsonrpc.rs
use serde::{Deserialize, Serialize};
use serde_json::Value;

/// Incoming JSON-RPC message from the client.
/// We use an untagged enum to handle requests (have id) vs notifications (no id).
#[derive(Debug, Deserialize)]
#[serde(untagged)]
pub enum IncomingMessage {
    Request(Request),
    Notification(Notification),
}

#[derive(Debug, Deserialize)]
pub struct Request {
    pub jsonrpc: String,
    pub id: Value,   // Can be number or string per JSON-RPC spec
    pub method: String,
    pub params: Option<Value>,
}

#[derive(Debug, Deserialize)]
pub struct Notification {
    pub jsonrpc: String,
    pub method: String,
    pub params: Option<Value>,
}

/// Outgoing JSON-RPC response.
#[derive(Debug, Serialize)]
pub struct Response {
    pub jsonrpc: &'static str,
    pub id: Value,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub result: Option<Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<RpcError>,
}

impl Response {
    pub fn success(id: Value, result: Value) -> Self {
        Self {
            jsonrpc: "2.0",
            id,
            result: Some(result),
            error: None,
        }
    }

    pub fn error(id: Value, code: i32, message: impl Into<String>) -> Self {
        Self {
            jsonrpc: "2.0",
            id,
            result: None,
            error: Some(RpcError {
                code,
                message: message.into(),
            }),
        }
    }
}

/// Outgoing JSON-RPC notification (no id, no response expected).
#[derive(Debug, Serialize)]
pub struct OutgoingNotification {
    pub jsonrpc: &'static str,
    pub method: &'static str,
    pub params: Value,
}

impl OutgoingNotification {
    pub fn new(method: &'static str, params: Value) -> Self {
        Self {
            jsonrpc: "2.0",
            method,
            params,
        }
    }
}

#[derive(Debug, Serialize)]
pub struct RpcError {
    pub code: i32,
    pub message: String,
}

// Standard JSON-RPC error codes
pub const PARSE_ERROR: i32 = -32700;
pub const METHOD_NOT_FOUND: i32 = -32601;
pub const INVALID_PARAMS: i32 = -32602;
pub const INTERNAL_ERROR: i32 = -32603;

---

Step 2: Define ACP-Specific Types

// src/acp_types.rs
use serde::{Deserialize, Serialize};
use serde_json::Value;

/// The protocolVersion for ACP is an integer (unlike MCP which uses date strings).
/// Current version is 1.
pub const PROTOCOL_VERSION: u32 = 1;

// ─── initialize ──────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct InitializeParams {
    pub protocol_version: u32,
    pub client_capabilities: Option<ClientCapabilities>,
    pub client_info: Option<PeerInfo>,
}

#[derive(Debug, Deserialize, Default)]
pub struct ClientCapabilities {
    pub fs: Option<FsCapabilities>,
    pub terminal: Option<bool>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FsCapabilities {
    pub read_text_file: Option<bool>,
    pub write_text_file: Option<bool>,
}

#[derive(Debug, Deserialize, Serialize)]
pub struct PeerInfo {
    pub name: String,
    pub title: Option<String>,
    pub version: Option<String>,
}

#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct InitializeResult {
    pub protocol_version: u32,
    pub agent_capabilities: AgentCapabilities,
    pub agent_info: PeerInfo,
    pub auth_methods: Vec<Value>,
}

#[derive(Debug, Serialize, Default)]
#[serde(rename_all = "camelCase")]
pub struct AgentCapabilities {
    pub load_session: bool,
    pub prompt_capabilities: PromptCapabilities,
}

#[derive(Debug, Serialize, Default)]
pub struct PromptCapabilities {
    pub image: bool,
    pub audio: bool,
    #[serde(rename = "embeddedContext")]
    pub embedded_context: bool,
}

// ─── session/new ─────────────────────────────────────────────────────────────

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionNewParams {
    pub cwd: String,
    pub mcp_servers: Option<Vec<McpServerConfig>>,
}

#[derive(Debug, Deserialize, Serialize, Clone)]
pub struct McpServerConfig {
    pub name: String,
    pub command: Option<String>,
    pub args: Option<Vec<String>>,
}

#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionNewResult {
    pub session_id: String,
}

// ─── session/prompt ──────────────────────────────────────────────────────────

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionPromptParams {
    pub session_id: String,
    pub turn: PromptTurn,
}

#[derive(Debug, Deserialize)]
pub struct PromptTurn {
    pub content: Vec<ContentBlock>,
}

#[derive(Debug, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentBlock {
    Text { text: String },
    // Other types (image, audio, resource) omitted for this minimal implementation
}

#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionPromptResult {
    pub stop_reason: StopReason,
}

#[derive(Debug, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum StopReason {
    EndTurn,
    MaxTokens,
    StopSequence,
    Error,
}

// ─── session/update notification ─────────────────────────────────────────────

#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionUpdateParams {
    pub session_id: String,
    pub update: SessionUpdate,
}

#[derive(Debug, Serialize)]
#[serde(tag = "sessionUpdate", rename_all = "snake_case")]
pub enum SessionUpdate {
    AgentMessageChunk {
        content: TextContent,
    },
    // Other update types: thought_chunk, tool_call, diff, etc.
}

#[derive(Debug, Serialize)]
pub struct TextContent {
    #[serde(rename = "type")]
    pub content_type: &'static str,
    pub text: String,
}

---

Step 3: The Agent State

// src/agent.rs
use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use uuid::Uuid;

/// Represents an active conversation session.
pub struct Session {
    pub id: String,
    pub cwd: String,
}

/// Shared state for the agent.
#[derive(Clone)]
pub struct AgentState {
    sessions: Arc<Mutex<HashMap<String, Session>>>,
}

impl AgentState {
    pub fn new() -> Self {
        Self {
            sessions: Arc::new(Mutex::new(HashMap::new())),
        }
    }

    /// Creates a new session and returns its ID.
    pub fn create_session(&self, cwd: String) -> String {
        let id = format!("sess_{}", Uuid::new_v4().simple());
        let session = Session {
            id: id.clone(),
            cwd,
        };
        self.sessions.lock().unwrap().insert(id.clone(), session);
        id
    }

    /// Checks if a session exists.
    pub fn session_exists(&self, id: &str) -> bool {
        self.sessions.lock().unwrap().contains_key(id)
    }
}

---

Step 4: The Main Dispatch Loop

This is the core of the ACP agent: read a line from stdin, parse it as JSON-RPC, dispatch to the right handler, write the response(s) to stdout.

// src/main.rs
mod jsonrpc;
mod acp_types;
mod agent;

use anyhow::Result;
use serde_json::{Value, json};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};

use acp_types::*;
use agent::AgentState;
use jsonrpc::*;

/// Write a single JSON message to stdout followed by newline.
/// This is the only function that writes to stdout.
async fn write_message<T: serde::Serialize>(
    stdout: &mut tokio::io::Stdout,
    msg: &T,
) -> Result<()> {
    let mut line = serde_json::to_string(msg)?;
    line.push('\n');
    stdout.write_all(line.as_bytes()).await?;
    stdout.flush().await?;
    Ok(())
}

/// Send a session/update notification — used for streaming output.
async fn send_update(
    stdout: &mut tokio::io::Stdout,
    session_id: &str,
    update: SessionUpdate,
) -> Result<()> {
    let notification = OutgoingNotification::new(
        "session/update",
        serde_json::to_value(SessionUpdateParams {
            session_id: session_id.to_string(),
            update,
        })?,
    );
    write_message(stdout, &notification).await
}

/// Handle the `initialize` request.
async fn handle_initialize(
    params: Option<Value>,
) -> Result<Value> {
    // Parse params (tolerant of missing fields)
    let _params: Option<InitializeParams> = params
        .as_ref()
        .and_then(|p| serde_json::from_value(p.clone()).ok());

    let result = InitializeResult {
        protocol_version: PROTOCOL_VERSION,
        agent_capabilities: AgentCapabilities {
            load_session: false,
            prompt_capabilities: PromptCapabilities {
                image: false,
                audio: false,
                embedded_context: false,
            },
        },
        agent_info: PeerInfo {
            name: "acp-agent-rs".to_string(),
            title: Some("ACP Agent (Rust)".to_string()),
            version: Some(env!("CARGO_PKG_VERSION").to_string()),
        },
        auth_methods: vec![],
    };

    Ok(serde_json::to_value(result)?)
}

/// Handle the `session/new` request.
async fn handle_session_new(
    state: &AgentState,
    params: Option<Value>,
) -> Result<Value> {
    let params: SessionNewParams = params
        .ok_or_else(|| anyhow::anyhow!("Missing params"))
        .and_then(|p| serde_json::from_value(p).map_err(Into::into))?;

    let session_id = state.create_session(params.cwd);

    Ok(serde_json::to_value(SessionNewResult { session_id })?)
}

/// Handle the `session/prompt` request.
///
/// This is the main turn handler. We:
/// 1. Parse the incoming prompt
/// 2. Send streaming session/update notifications as we "process"
/// 3. Return the final session/prompt response with stop_reason
async fn handle_session_prompt(
    state: &AgentState,
    stdout: &mut tokio::io::Stdout,
    params: Option<Value>,
) -> Result<Value> {
    let params: SessionPromptParams = params
        .ok_or_else(|| anyhow::anyhow!("Missing params"))
        .and_then(|p| serde_json::from_value(p).map_err(Into::into))?;

    if !state.session_exists(&params.session_id) {
        anyhow::bail!("Unknown session: {}", params.session_id);
    }

    // Extract text from the user's content blocks
    let user_text: String = params
        .turn
        .content
        .iter()
        .filter_map(|block| match block {
            ContentBlock::Text { text } => Some(text.as_str()),
        })
        .collect::<Vec<_>>()
        .join(" ");

    tracing::info!("User prompt in session {}: {}", params.session_id, user_text);

    // Stream the response back using session/update notifications.
    // In a real agent this is where you'd call an LLM and stream tokens.
    let response_text = format!(
        "I received your message: \"{}\". \
        (This is a placeholder response from the Rust ACP agent. \
        Wire up an LLM here.)",
        user_text
    );

    // Send the response in chunks to demonstrate streaming
    for chunk in response_text.split_whitespace().collect::<Vec<_>>().chunks(5) {
        let text = chunk.join(" ") + " ";
        send_update(
            stdout,
            &params.session_id,
            SessionUpdate::AgentMessageChunk {
                content: TextContent {
                    content_type: "text",
                    text,
                },
            },
        )
        .await?;
    }

    // Return the final response with stop reason
    let result = SessionPromptResult {
        stop_reason: StopReason::EndTurn,
    };

    Ok(serde_json::to_value(result)?)
}

#[tokio::main]
async fn main() -> Result<()> {
    // IMPORTANT: Log to stderr only.
    // stdout is the ACP protocol wire — any stray bytes will corrupt the framing.
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::from_default_env()
                .add_directive(tracing::Level::INFO.into()),
        )
        .with_writer(std::io::stderr)
        .with_ansi(false)
        .init();

    tracing::info!("ACP agent starting");

    let state = AgentState::new();
    let stdin = tokio::io::stdin();
    let mut stdout = tokio::io::stdout();
    let mut reader = BufReader::new(stdin);
    let mut line = String::new();

    loop {
        line.clear();
        let bytes_read = reader.read_line(&mut line).await?;

        // EOF — the client closed its end of the connection
        if bytes_read == 0 {
            tracing::info!("EOF on stdin, shutting down");
            break;
        }

        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }

        tracing::debug!("Received: {}", trimmed);

        // Parse as JSON-RPC
        let message: IncomingMessage = match serde_json::from_str(trimmed) {
            Ok(m) => m,
            Err(e) => {
                tracing::warn!("Failed to parse message: {}", e);
                // Send parse error back (use null id per JSON-RPC spec for unparseable messages)
                let err_response =
                    Response::error(Value::Null, PARSE_ERROR, format!("Parse error: {}", e));
                write_message(&mut stdout, &err_response).await?;
                continue;
            }
        };

        match message {
            IncomingMessage::Request(req) => {
                tracing::debug!("Handling request: {} (id: {})", req.method, req.id);

                let result = match req.method.as_str() {
                    "initialize" => {
                        handle_initialize(req.params).await
                    }
                    "session/new" => {
                        handle_session_new(&state, req.params).await
                    }
                    "session/prompt" => {
                        // Note: handle_session_prompt writes notifications to stdout
                        // before returning the final result.
                        handle_session_prompt(&state, &mut stdout, req.params).await
                    }
                    unknown => {
                        Err(anyhow::anyhow!("Unknown method: {}", unknown))
                    }
                };

                let response = match result {
                    Ok(value) => Response::success(req.id, value),
                    Err(e) => {
                        tracing::error!("Error handling {}: {}", req.method, e);
                        if req.method == "initialize" || req.method == "session/new" {
                            Response::error(req.id, INVALID_PARAMS, e.to_string())
                        } else {
                            Response::error(req.id, METHOD_NOT_FOUND, e.to_string())
                        }
                    }
                };

                write_message(&mut stdout, &response).await?;
            }

            IncomingMessage::Notification(notif) => {
                // Clients can send session/cancel as a notification
                tracing::debug!("Received notification: {}", notif.method);
                match notif.method.as_str() {
                    "session/cancel" => {
                        tracing::info!("Session cancel received");
                        // In a real implementation, cancel ongoing operations
                    }
                    _ => {
                        tracing::debug!("Unhandled notification: {}", notif.method);
                    }
                }
            }
        }
    }

    Ok(())
}

---

Building

cargo build --release

---

Testing the Protocol Manually

Since ACP is newline-delimited JSON-RPC over stdio, you can test the protocol sequence directly with a shell pipeline. The messages must be sent sequentially as ACP is stateful.

Write a test script:

#!/bin/bash
# test_acp.sh

AGENT=./target/release/acp-agent

(
  # 1. Initialize
  echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'
  sleep 0.1

  # 2. Create a session
  echo '{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/tmp/project","mcpServers":[]}}'
  sleep 0.1

  # 3. Send a prompt (use the sessionId from the session/new response)
  echo '{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"REPLACE_WITH_SESSION_ID","turn":{"content":[{"type":"text","text":"Hello, what can you do?"}]}}}'
  sleep 0.5
) | $AGENT 2>/dev/null

The output will be (simplified):

{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":1,"agentCapabilities":{...},"agentInfo":{...},"authMethods":[]}}
{"jsonrpc":"2.0","id":1,"result":{"sessionId":"sess_a1b2c3d4..."}}
{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"sess_a1b2c3d4...","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"I received ..."}}}}
{"jsonrpc":"2.0","id":2,"result":{"stopReason":"end_turn"}}

---

Registering with Zed

To use your agent in Zed, add it to Zed's agent configuration (check Zed's ACP documentation for the exact format, as it evolves with new releases):

{
  "agent": {
    "provider": {
      "type": "acp",
      "command": "/path/to/acp-agent/target/release/acp-agent",
      "args": []
    }
  }
}

---

What to Add Next

This is a skeleton. A production ACP agent built on this foundation would add:

Actual LLM Integration

Replace the placeholder response in handle_session_prompt with a call to an LLM API (e.g., OpenAI, Anthropic, a local Ollama instance). Stream tokens as they arrive using session/update notifications.

// Pseudocode for streaming LLM responses
while let Some(chunk) = llm_stream.next().await {
    send_update(stdout, &session_id, SessionUpdate::AgentMessageChunk {
        content: TextContent { content_type: "text", text: chunk },
    }).await?;
}

MCP Client Integration

The session/new params include a list of MCP servers for the agent to connect to. Use rmcp (the Rust MCP SDK) to connect to those servers and make tools available to your LLM:

// Connect to MCP servers listed in session/new
use rmcp::{ServiceExt, transport::TokioChildProcess};

for server_config in &session_params.mcp_servers {
    if let Some(command) = &server_config.command {
        let client = ().serve(TokioChildProcess::new(
            tokio::process::Command::new(command)
        )?).await?;
        // Register client's tools with your LLM
    }
}

File System Access (Client Methods)

If the client declares fs.readTextFile: true during initialization, you can call back to the client to read files:

// Request a file read from the client
let request = Request {
    jsonrpc: "2.0".to_string(),
    id: json!(next_id()),
    method: "fs/read_text_file".to_string(),
    params: Some(json!({ "path": "/absolute/path/to/file.rs" })),
};
write_message(stdout, &request).await?;
// Then read the response from stdin

Permission Gating

Before executing destructive tool calls, use session/request_permission:

let perm_request = Request {
    jsonrpc: "2.0".to_string(),
    id: json!(next_id()),
    method: "session/request_permission".to_string(),
    params: Some(json!({
        "sessionId": session_id,
        "permission": {
            "type": "tool_call",
            "toolName": "write_file",
            "description": "Write to /src/main.rs"
        }
    })),
};
write_message(stdout, &perm_request).await?;
// Wait for approval before proceeding

---

Key Rules to Remember

1. All logging goes to stderr. stdout is the protocol wire. println! is off-limits. Use tracing with .with_writer(std::io::stderr).

2. Notifications have no id field. If you accidentally include one, the client may treat it as a response to a request.

3. session/prompt must not return until all session/update notifications are sent. The client considers the turn complete when it receives the session/prompt response.

4. Protocol version is an integer (1), not a date string. ACP uses "protocolVersion": 1, unlike MCP which uses "protocolVersion": "2025-06-18".

5. File paths must be absolute. The spec requires all path arguments to be absolute paths.

---

Protocol Spec Reference

• ACP Protocol Overview

• ACP Initialization

• ACP Session Setup

• ACP Prompt Turn

• ACP GitHub Repository