> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="ClientSideConnection">
    The main connection class that communicates with agents. It implements the `Agent` interface, providing methods like `initialize()`, `newSession()`, and `prompt()`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Communication Model

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

```typescript theme={null}
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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="ClientSideConnection" icon="plug" href="/clients/client-side-connection">
    Learn about the connection class and its methods
  </Card>

  <Card title="Client Interface" icon="code" href="/clients/implementing-client-interface">
    Implement the required Client interface
  </Card>

  <Card title="Session Updates" icon="arrows-rotate" href="/clients/handling-updates">
    Handle real-time updates from the agent
  </Card>

  <Card title="Permissions" icon="shield-check" href="/clients/permission-requests">
    Implement permission request UI
  </Card>
</CardGroup>

## Full Example

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

```bash theme={null}
# Clone the repository
git clone https://github.com/agentclientprotocol/typescript-sdk
cd typescript-sdk

# Run the example
npm install
npm run example:client
```

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