Building Clients

Learn how to build ACP clients that connect to agents

What is a Client?

In the Agent-Client Protocol (ACP), a client is the application that provides the interface between users and AI agents. Clients are typically:

• Code editors (VS Code, JetBrains IDEs, Vim/Neovim)
• Terminal applications
• Web-based IDEs
• Custom developer tools

The client is responsible for:

• Creating and managing connections to agents
• Handling user input and displaying agent responses
• Managing file system access and security
• Requesting and displaying permission prompts
• Running terminal commands on behalf of the agent

Architecture Overview

The ACP TypeScript SDK provides two main components for building clients:

1. ClientSideConnection

   The main connection class that communicates with agents. It implements the Agent interface, providing methods like initialize(), newSession(), and prompt().

2. Client Interface

   Your client implementation must implement the Client interface, which handles incoming requests from the agent such as permission requests, session updates, and file system operations.

Communication Model

ACP uses a bidirectional JSON-RPC 2.0 protocol over standard input/output (stdin/stdout):

Client                           Agent
  |                                |
  |-- initialize request --------->|
  |<-- initialize response --------|
  |                                |
  |-- newSession request --------->|
  |<-- newSession response --------|
  |                                |
  |-- prompt request ------------->|
  |<-- sessionUpdate notification -| (many)
  |<-- requestPermission request --|
  |-- requestPermission response ->|
  |<-- prompt response ------------|

Client Responsibilities

1. Session Management

Clients create and manage conversation sessions, each with its own context and history.

2. Permission Control

Clients must implement permission requests to give users control over what the agent can do.

3. Resource Access

Clients provide sandboxed access to:

• File system (read/write operations)
• Terminal execution
• Environment information

4. UI Updates

Clients handle real-time session updates to display:

• Agent messages and thoughts
• Tool call progress
• Execution plans
• Error states

Example Client

Here’s a minimal client implementation:

import * as acp from "@agentclientprotocol/acp";
import { spawn } from "node:child_process";

class MyClient implements acp.Client {
  async requestPermission(
    params: acp.RequestPermissionRequest
  ): Promise<acp.RequestPermissionResponse> {
    // Show permission prompt to user
    const selectedOption = await showPermissionUI(params);
    return {
      outcome: {
        outcome: "selected",
        optionId: selectedOption,
      },
    };
  }

  async sessionUpdate(params: acp.SessionNotification): Promise<void> {
    // Update UI with agent progress
    updateUI(params.update);
  }

  async readTextFile(
    params: acp.ReadTextFileRequest
  ): Promise<acp.ReadTextFileResponse> {
    const content = await fs.readFile(params.uri, "utf-8");
    return { content };
  }

  async writeTextFile(
    params: acp.WriteTextFileRequest
  ): Promise<acp.WriteTextFileResponse> {
    await fs.writeFile(params.uri, params.content);
    return {};
  }
}

// Create connection
const agentProcess = spawn("my-agent");
const stream = acp.ndJsonStream(
  Writable.toWeb(agentProcess.stdin),
  Readable.toWeb(agentProcess.stdout)
);

const client = new MyClient();
const connection = new acp.ClientSideConnection(
  (_agent) => client,
  stream
);

// Initialize and use
await connection.initialize({
  protocolVersion: acp.PROTOCOL_VERSION,
  clientCapabilities: {
    fs: {
      readTextFile: true,
      writeTextFile: true,
    },
  },
});

const session = await connection.newSession({
  cwd: process.cwd(),
  mcpServers: [],
});

await connection.prompt({
  sessionId: session.sessionId,
  prompt: [{ type: "text", text: "Hello!" }],
});

Next Steps

ClientSideConnection

Learn about the connection class and its methods

Client Interface

Implement the required Client interface

Session Updates

Handle real-time updates from the agent

Permissions

Implement permission request UI

Full Example

For a complete working example, see the example client in the SDK repository:

# Clone the repository
git clone https://github.com/agentclientprotocol/typescript-sdk
cd typescript-sdk

# Run the example
npm install
npm run example:client

The example client demonstrates all client capabilities including file system operations, terminal management, and permission handling.