ACP Dart Library

The official Dart implementation of the Agent Client Protocol (ACP) — a standardized communication protocol between code editors and AI-powered coding agents.

Learn more at https://agentclientprotocol.com

Installation

Add the package to your pubspec.yaml:

dependencies:
  acp_dart: ^0.4.0

Then run:

dart pub get

Get Started

Understand the Protocol

Start by reading the ACP documentation to understand the core concepts and protocol specification.

Try the Examples

The examples directory contains simple implementations of both Agents and Clients in Dart. These examples can be run from your terminal or from an ACP Client like Zed, making them great starting points for your own integration!

To run the example agent:

dart run example/agent.dart

To run the example client:

dart run example/client.dart

Explore the API

The library provides:

Agent-side: AgentSideConnection for implementing AI agents
Client-side: ClientSideConnection for implementing ACP clients
Core types: Comprehensive schema definitions for all ACP messages
RPC unions: Type-safe request, response, and notification unions for exhaustive handling
Stream handling: ndJsonStream for NDJSON-based communication
Type safety: Full Dart type annotations and null safety

If you're building an Agent, start with implementing the Agent interface and using AgentSideConnection.

If you're building a Client, start with implementing the Client interface and using ClientSideConnection.

Key Features

Type Safety: Full Dart type annotations with null safety
RPC Unions: Sealed union types for exhaustive request/response handling
JSON Serialization: Automatic serialization using json_serializable
Stream-based Communication: NDJSON-based communication over stdio
Error Handling: Comprehensive error types and handling mechanisms
JSON-RPC Error Mapping: Parameter-validation failures map to -32602 Invalid params, while unexpected failures map to -32603 Internal error
Protocol Cancellation: Typed $/cancel_request notifications with -32800 cancelled error semantics
Extensible: Support for extension methods and notifications (method names are passed through as provided; include leading _ for protocol extension methods)

Protocol Support Matrix

The implementation tracks ACP stable and unstable surfaces explicitly.

Stable Supported

Agent methods: initialize, authenticate, session/new, session/load, session/prompt, session/cancel, session/set_mode, session/set_config_option
Client methods: fs/read_text_file, fs/write_text_file, session/request_permission, session/update
Terminal methods: terminal/create, terminal/output, terminal/wait_for_exit, terminal/kill, terminal/release
Protocol cancellation notification: $/cancel_request
Session updates: user_message_chunk, agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update, plan, available_commands_update, current_mode_update, config_option_update

Unstable Supported

session/list
session/fork
session/resume
session/set_model
Additional update variants implemented for parity tracking: session_info_update, usage_update

Known Unsupported / Partial

Filesystem methods beyond ACP stable surface (for example delete/move/mkdir/list operations)
Any ACP methods or update variants not represented in agentMethods, clientMethods, and typed schema unions in this package

See parity_verification_checklist.md for the release-time parity verification process.

Error and Stream Behavior

Incoming request parameter/validation failures are returned as JSON-RPC Invalid params (-32602).
Unexpected runtime failures are returned as JSON-RPC Internal error (-32603) without exposing raw internal exception details.
ndJsonStream skips malformed non-empty lines and continues processing subsequent valid messages. Use the optional onParseError callback to handle parse diagnostics (for example, routing logs to stderr or a structured logger).

Usage Examples

Creating an Agent

import 'package:acp_dart/acp_dart.dart';

class MyAgent implements Agent {
  final AgentSideConnection _connection;

  MyAgent(this._connection);

  @override
  Future<InitializeResponse> initialize(InitializeRequest params) async {
    return InitializeResponse(
      protocolVersion: '0.1.0',
      capabilities: AgentCapabilities(
        loadSession: false,
        auth: [],
      ),
    );
  }

  // Implement other required methods...
}

void main() {
  final stream = ndJsonStream(stdin, stdout);
  final connection = AgentSideConnection((conn) => MyAgent(conn), stream);
}

Creating a Client

import 'package:acp_dart/acp_dart.dart';

class MyClient implements Client {
  @override
  Future<RequestPermissionResponse> requestPermission(
    RequestPermissionRequest params,
  ) async {
    // Handle permission requests
    return RequestPermissionResponse(optionId: params.options.first.id);
  }

  @override
  Future<void> sessionUpdate(SessionNotification params) async {
    // Handle session updates
    print('Session update: ${params.update}');
  }

  // Implement other required methods...
}

Resources

Contributing

See the official ACP repository for contribution guidelines.