DOCSEARCHbyAlgolia
Submit Docs

Agent Client Protocol (ACP) Documentation

repository·main·Indexed 25 days ago

https://github.com/agentclientprotocol/agent-client-protocol

A standard protocol for communication between code editors (clients) and AI coding agents. It provides a structured way to handle JSON-RPC messages, session notifications, permission requests, and file/terminal operations. The project includes official SDKs for Kotlin, Java, Python, Rust, and TypeScript, as well as the agent-client-protocol-schema Rust crate for low-level data models and JSON Schema artifacts.

Tokens
160.6K
Snippets
214
Records
1.1K
Agent score
84%

What's inside Agent Client Protocol

  1. Overview of the new Rust SDK (SACP-based)

    main

    The new Rust SDK for the Agent Client Protocol (ACP) is based on the SACP (Symposium ACP) implementation. It moves away from a simple trait-based callback model to a component-based architecture. Key improvements include:

    • Builder Patterns: For constructing components and connections.
    • Explicit Directional Naming: Uses types like ClientToAgent and AgentToClient to clarify peer relationships and support multiple peers (essential for proxies).
    • Connection Context (cx): Handlers receive a context object that allows them to send requests and notifications back through the connection, enabling streaming progress.
    • Dynamic Handlers: Supports adding/removing closure-based handlers that can be specific to a particular session.
    • Ordering Guarantees: Provides mechanisms to ensure messages are processed in order and that notifications are handled before a response is sent.
    • Starvation-Free APIs: Designed to prevent common async Rust pitfalls where message processing is blocked during long-running tasks.

  3. View available ACP agents in the Registry

    main

    The ACP Registry provides a list of available agents that implement the Agent Client Protocol. These agents can be used for various tasks, including coding, CLI interactions, and pipeline automation.

    Currently available agents include:

    • Gemini CLI: Google's official CLI for Gemini.
    • GitHub Copilot: GitHub's AI pair programmer.
    • GLM Agent: An ACP agent powered by Zhipu AI's GLM Coding Plan models. Supports streaming, tool calls, mid-session model switching, image input, and session persistence.
    • goose: A local, extensible, open source AI agent for automating engineering tasks.
    • Grok Build: xAI's coding agent and CLI.
    • Harn: Runs .harn agent pipelines as a native ACP coding agent over stdio.

  4. Understand the End-Turn Token Usage proposal

    main

    The Agent Client Protocol (ACP) is proposing a standardized way for agents to report token usage when a prompt turn completes. This allows clients to show consistent token breakdowns (input, output, reasoning, etc.) for specific turns without conflating them with cumulative session costs or context window sizes.

    Note: This feature is currently in Draft status and is not yet part of the stable Preview. Implementation in Rust crates may be gated behind the unstable_end_turn_token_usage feature flag.

  5. Compatible Agents for ACP Clients

    main

    The Agent Client Protocol (ACP) is supported by a wide range of AI agents and tools. You can use an ACP Client to interact with any of the following agents, some of which may require specific adapters or servers:

    Native ACP Support

    • AgentPool
    • Augment Code
    • AutoDev
    • Blackbox AI
    • Cline
    • Code Assistant
    • Construct
    • crow-cli
    • Cursor
    • Docker's cagent
    • fast-agent
    • Factory Droid
    • fount
    • Gemini CLI
    • GitHub Copilot (Public Preview)
    • Goose
    • Hermes Agent
    • Junie by JetBrains
    • Kimi CLI
    • Kiro CLI
    • Minion Code
    • Mistral Vibe
    • OpenClaw
    • OpenCode
    • OpenHands
    • Poolside
    • Qoder CLI
    • Qwen Code
    • siGit Code
    • Stakpak
    • stdio Bus
    • VT Code

    Agents via Adapters or Specific Servers

    • Bub: via bub-acp-server
    • Claude Agent: via Zed's SDK adapter
    • Codex CLI: via Zed's adapter
    • Pi: via pi-acp adapter

  6. View available agents in the ACP Registry

    main

    The ACP Registry contains a list of available AI agents that implement the Agent Client Protocol. Below are the currently listed agents and their respective versions:

    • Junie: AI Coding Agent by JetBrains (2383.10.0)
    • Kilo: The open source coding agent (7.4.17)
    • Kimi CLI: Moonshot AI's coding assistant (1.49.0)
    • Minion Code: Enhanced AI code assistant built on the Minion framework (0.1.44)
    • Mistral Vibe: Mistral's open-source coding assistant (2.23.1)
    • Nova: Nova by Compass AI - a fully-fledged software engineer (1.1.29)
    • OpenCode: The open source coding agent (1.18.9)
    • pi ACP: ACP adapter for pi coding agent (0.0.32)
    • Poolside: Poolside's coding agent (1.0.13)
    • Qoder CLI: AI coding assistant with agentic capabilities (0.2.14)

  8. Understand ACP v2 core changes and themes

    main

    ACP v2 introduces several architectural shifts to improve flexibility and consistency:

    • Decoupled Prompt Lifecycle: session/update notifications are no longer strictly tied to user-initiated turns. A prompt response indicates message acknowledgment, not the end of work. Agents can provide real-time updates for background work while remaining ready for new input.
    • Uniform Message Patching: User/agent messages, tool calls, and terminal output use stable IDs for patching. Omitted fields remain unchanged, null clears a field, values replace existing data, and chunks append to existing data.
    • Structured File Diffs: The oldText/newText pattern is replaced by structured file changes (add, delete, modify, move, copy, and binary/non-text cases). Agents can optionally provide a git_patch for rendering.
    • Flexible Permission Requests: Permission prompts now include a required title, an optional description, and an extensible subject (replacing the hard-wired tool call pattern).
    • Enhanced Extensibility: Enum-like values across the schema now support unknown variants using a _ prefix for implementation-specific extensions, ensuring forward compatibility.

  9. Understand the Agent Client Protocol (ACP) Communication Model

    main

    The Agent Client Protocol (ACP) uses the JSON-RPC 2.0 specification to enable communication between Agents and Clients. Messages fall into two categories:

    • Methods: Request-response pairs that expect a result or an error.
    • Notifications: One-way messages that do not expect a response.

    Key Conventions:

    • JSON object property keys use camelCase (unless specified otherwise in the schema).
    • String values in discriminator fields use snake_case.
    • All file paths MUST be absolute.
    • Line numbers are 1-based.

  10. Understand the Agent Client Protocol Communication Model

    main

    The Agent Client Protocol (v1 draft) uses the JSON-RPC 2.0 specification for communication between Agents and Clients. It supports two message types:

    • Methods: Request-response pairs that expect a result or an error.
    • Notifications: One-way messages that do not expect a response.

    All file paths used in the protocol MUST be absolute, and line numbers are 1-based.

  11. Understand the Rust SDK crate structure

    main

    The Agent Client Protocol (ACP) Rust SDK is organized into several specialized crates. Depending on your use case, you may need to include specific crates in your Cargo.toml:

    • agent-client-protocol: The core SDK containing builder patterns, link types, and component abstractions.
    • agent-client-protocol-tokio: Provides integration for the Tokio runtime (handling spawns, timers, and I/O).
    • agent-client-protocol-rmcp: A bridge to the rmcp crate for MCP (Model Context Protocol) integration.
    • agent-client-protocol-conductor: A reference implementation of a conductor.
    • agent-client-protocol-derive: Contains derive macros for JSON-RPC traits.
    • agent-client-protocol-test: Provides test utilities and mock implementations.
    • agent-client-protocol-tee: A debugging proxy used to log all traffic.
    • agent-client-protocol-trace-viewer: An interactive viewer for sequence diagrams generated from trace files.

  12. Understand the ACP v2 Prompt Lifecycle

    main

    In ACP v2, a prompt initiates or contributes to foreground work within a session. The lifecycle follows these principles:

    • Prompt Duration: The session/prompt message is transient; it only lasts until the Agent accepts the prompt.
    • State Updates: Once a prompt is accepted, the Agent communicates the accepted user message, the current running state, the generated output, and the completion status via session/update notifications.
    • Agent Autonomy: An Agent may continue working (including multiple model exchanges and tool invocations) until it explicitly reports an idle state.