Skip to main content

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us