Skip to main content

​
What is ACP?

The Agent Client Protocol (ACP) is a standardized communication protocol that enables seamless interaction between code editors (clients) and AI-powered coding agents. It provides a structured way for AI assistants to understand context, execute tools, and collaborate with developers in real-time. Learn more about the protocol at agentclientprotocol.com

​
What is ACP Dart?

The ACP Dart SDK is the official Dart implementation of the Agent Client Protocol. It provides a complete, type-safe implementation that makes it easy to:

Build AI Agents

Create intelligent agents that process prompts, execute tools, and interact with development environments

Build ACP Clients

Implement code editors or IDEs that communicate with AI agents through the standardized protocol

Type-Safe Communication

Leverage full Dart type annotations with null safety for robust, error-free implementations

Stream-Based Protocol

Use NDJSON-based communication over stdio for efficient, real-time data exchange

​
Key Features

​
Type Safety

Full Dart type annotations with null safety ensure your code is robust and catches errors at compile time: 
Future<InitializeResponse> initialize(InitializeRequest params) async {
  return InitializeResponse(
    protocolVersion: 1,
    agentCapabilities: AgentCapabilities(loadSession: false),
    authMethods: const [],
  );
}

​
RPC Unions

Sealed union types enable exhaustive request/response handling with pattern matching: 
switch (outcome) {
  case SelectedOutcome(optionId: final id):
    // Handle selected option
    break;
  case CancelledOutcome():
    // Handle cancellation
    break;
}

​
Stream-Based Communication

Built-in NDJSON stream handling for stdio-based communication: 
final stream = ndJsonStream(stdin, stdout);
final connection = AgentSideConnection((conn) => MyAgent(conn), stream);

​
Comprehensive Error Handling

  • Parameter validation failures map to -32602 Invalid params
  • Unexpected runtime failures map to -32603 Internal error
  • Protocol cancellation with -32800 cancelled error semantics
  • Type-safe error types: RequestError, ErrorResponse

​
Protocol Support

The SDK tracks both stable and unstable ACP surfaces:

​
Stable Methods

  • initialize - Establish connection and negotiate capabilities
  • authenticate - Handle authentication requests
  • session/new - Create new conversation sessions
  • session/load - Load existing sessions
  • session/prompt - Process user prompts
  • session/cancel - Cancel ongoing operations
  • session/set_mode - Switch agent modes
  • session/set_config_option - Configure session options
  • fs/read_text_file - Read file contents
  • fs/write_text_file - Write file contents
  • session/request_permission - Request user permissions
  • session/update - Send session updates
  • terminal/create - Create new terminals
  • terminal/output - Get terminal output
  • terminal/wait_for_exit - Wait for command completion
  • terminal/kill - Kill running commands
  • terminal/release - Release terminal resources

​
Unstable Methods

These methods are experimental and may change in future versions:
  • session/list - List available sessions
  • session/fork - Fork existing sessions
  • session/resume - Resume sessions without replay
  • session/set_model - Change the active model

​
Core Components

The library provides several key components:
ComponentPurpose
AgentSideConnectionImplement AI agents that process prompts and execute tools
ClientSideConnectionImplement ACP clients (editors/IDEs)
Agent interfaceDefine agent-side request handlers
Client interfaceDefine client-side request handlers
TerminalHandleManage terminal operations
ndJsonStreamHandle NDJSON-based communication
Schema typesComprehensive definitions for all ACP messages
RPC unionsType-safe request/response handling

​
Architecture

Building an Agent? Start with the Agent interface and AgentSideConnection to handle prompts and tool execution.Building a Client? Start with the Client interface and ClientSideConnection to integrate AI capabilities into your editor.

​
Next Steps

Installation

Install the ACP Dart SDK in your project

Quickstart

Build your first agent or client in minutes

Protocol Documentation

Deep dive into the ACP specification

Examples

Explore working examples on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us