Agent Client Protocol TypeScript Library

https://zed-industries.github.io/agent-client-protocol
Admin
The official TypeScript implementation of the Agent Client Protocol (ACP) — a standardized...
Tokens:35,777
Snippets:226
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install ACP TypeScript Library using npm

Source: https://zed-industries.github.io/agent-client-protocol/index

This command installs the official TypeScript implementation of the Agent Client Protocol (ACP) using npm. It is a prerequisite for building agents or clients that communicate using ACP.

```bash
npm install @zed-industries/agent-client-protocol
```

--------------------------------

### Client Interface - terminalOutput

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Client

Gets the current output and exit status of a terminal. Returns immediately without waiting for the command to complete.

```APIDOC
## POST /client/terminalOutput

### Description
Gets the current output and exit status of a terminal. Returns immediately without waiting for the command to complete. If the command has already exited, the exit status is included.

### Method
POST

### Endpoint
/client/terminalOutput

### Parameters
#### Request Body
- **params** (TerminalOutputRequest) - Required - The request parameters for getting terminal output.

### Request Example
```json
{
  "params": {
    "terminalId": "term-abc-123"
  }
}
```

### Response
#### Success Response (200)
- **output** (string) - The output from the terminal.
- **exitStatus** (number | null) - The exit status of the terminal command, or null if not exited.

#### Response Example
```json
{
  "output": "-rw-r--r-- 1 user group 1024 Jan 1  2023 file.txt\n",
  "exitStatus": 0
}
```
```

--------------------------------

### POST /initialize

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Establishes the connection with a client and negotiates protocol capabilities, including version and authentication methods.

```APIDOC
## POST /initialize

### Description
Establishes the connection with a client and negotiates protocol capabilities. This method is called once at the beginning of the connection to negotiate the protocol version, exchange capability information, and determine available authentication methods.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **params** (InitializeRequest) - Required - Initialization parameters including protocol version and capabilities.

### Request Example
```json
{
  "params": {
    "protocolVersion": "1.0",
    "capabilities": {
      "completion": true,
      "chat": false
    }
  }
}
```

### Response
#### Success Response (200)
- **protocolVersion** (string) - The agreed-upon protocol version.
- **capabilities** (object) - The agent's supported capabilities.

#### Response Example
```json
{
  "protocolVersion": "1.0",
  "capabilities": {
    "completion": true,
    "chat": false
  }
}
```
```

--------------------------------

### Terminal Output Request Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/TerminalOutputRequest

Defines the structure for a request to get the current output and status of a terminal.

```APIDOC
## TerminalOutputRequest

### Description
Request to get the current output and status of a terminal.

### Method
POST

### Endpoint
/terminals/{terminalId}/output

### Parameters
#### Path Parameters
- **terminalId** (string) - Required - The ID of the terminal to get output from.

#### Query Parameters

#### Request Body
- **sessionId** (string) - Required - The session ID for this request.
- **_meta** (object) - Optional - Extension point for implementations.

### Request Example
```json
{
  "sessionId": "your_session_id",
  "_meta": {
    "key": "value"
  }
}
```

### Response
#### Success Response (200)
- **output** (string) - The current output of the terminal.
- **status** (string) - The current status of the terminal.

#### Response Example
```json
{
  "output": "Terminal output here.",
  "status": "running"
}
```
```

--------------------------------

### AvailableCommand Properties Explanation

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/AvailableCommand

Provides a detailed explanation of each property within the AvailableCommand interface. It clarifies the type, optionality, and purpose of '_meta', 'description', 'input', and 'name'. '_meta' is an extension point, 'description' is human-readable, 'input' is for command arguments, and 'name' identifies the command.

```markdown
### Properties

*   **`Optional` _meta**
    `_meta?: { [k: string]: unknown }`
    Extension point for implementations
*   **description**
    `description: string`
    Human-readable description of what the command does.
*   **`Optional` input**
    `input?: null | UnstructuredCommandInput`
    Input for the command if required
*   **name**
    `name: string`
    Command name (e.g., `create_plan`, `research_codebase`).
```

--------------------------------

### Agent Interface - initialize

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Agent

Establishes the connection with a client and negotiates protocol capabilities, including protocol version and authentication methods.

```APIDOC
## POST /initialize

### Description
Establishes the connection with a client and negotiates protocol capabilities. This method is called once at the beginning of the connection to negotiate the protocol version, exchange capability information, and determine available authentication methods. The agent should respond with its supported protocol version and capabilities.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Request Body
- **params** (InitializeRequest) - Required - The initialization parameters.

### Response
#### Success Response (200)
- **InitializeResponse** (object) - The response containing initialization details.

#### Response Example
```json
{
  "protocolVersion": "4.0.0",
  "capabilities": [
    "loadSession",
    "setSessionMode"
  ],
  "authenticationMethods": [
    "apiKey"
  ]
}
```
```

--------------------------------

### TerminalHandle.currentOutput

Source: https://zed-industries.github.io/agent-client-protocol/classes/TerminalHandle

Retrieves the current output from the terminal without waiting for the command to finish. This method is useful for getting real-time feedback from a running process.

```typescript
currentOutput(): Promise<TerminalOutputResponse>
```

--------------------------------

### Initialize Connection with Agent

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Establishes the connection with a client and negotiates protocol capabilities. This method is called once at the beginning of the connection to negotiate the protocol version, exchange capabilities, and determine authentication methods. The agent responds with its supported protocol version and capabilities.

```typescript
initialize(params: InitializeRequest): Promise<InitializeResponse>
```

--------------------------------

### InitializeResponse Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/InitializeResponse

Describes the structure of the InitializeResponse, including optional meta information, agent capabilities, supported authentication methods, and the negotiated protocol version.

```APIDOC
## InitializeResponse Interface

### Description
Response from the initialize method. Contains the negotiated protocol version and agent capabilities.

### Properties

#### `Optional` _meta
- **Type**: `{ [k: string]: unknown }`
- **Description**: Extension point for implementations.

#### `Optional` agentCapabilities
- **Type**: `AgentCapabilities`
- **Description**: Capabilities of the agent.

#### `Optional` authMethods
- **Type**: `AuthMethod[]`
- **Description**: Authentication methods supported by the agent.

#### protocolVersion
- **Type**: `number`
- **Description**: The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent. The client should disconnect, if it doesn't support this version.

### Example Response Body
```json
{
  "_meta": {},
  "agentCapabilities": {},
  "authMethods": [],
  "protocolVersion": 1
}
```
```

--------------------------------

### Define ReadTextFileRequest Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/ReadTextFileRequest

Defines the structure for a request to read the content of a text file. This request requires the client to support the 'fs.readTextFile' capability. It includes optional parameters for metadata, line limit, and starting line number, along with mandatory path and session ID.

```typescript
interface ReadTextFileRequest {
  _meta?: { [k: string]: unknown };
  limit?: null | number;
  line?: null | number;
  path: string;
  sessionId: string;
}
```

--------------------------------

### PromptCapabilities Interface Definition

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/PromptCapabilities

Defines the structure for agent prompt capabilities, indicating support for audio, embedded context, and image content blocks. The '_meta' field allows for implementation-specific extensions.

```typescript
interface PromptCapabilities {
  _meta?: { [k: string]: unknown };
  audio?: boolean;
  embeddedContext?: boolean;
  image?: boolean;
}
```

--------------------------------

### TerminalHandle Constructor

Source: https://zed-industries.github.io/agent-client-protocol/classes/TerminalHandle

Initializes a new instance of the TerminalHandle class.

```APIDOC
## Constructors

### constructor

  * new TerminalHandle(
    id: string,
    sessionId: string,
    conn: Connection,
  ): TerminalHandle

#### Parameters
    * id: string - The unique identifier for the terminal.
    * sessionId: string - The session ID associated with the terminal.
    * conn: Connection - The connection object for communication.

#### Returns
TerminalHandle - A new instance of the TerminalHandle class.
```

--------------------------------

### Client Capabilities

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/ClientCapabilities

Describes the capabilities supported by the client, such as file system access and terminal support.

```APIDOC
## Interface ClientCapabilities

Capabilities supported by the client.

### Properties

*   **`_meta`** (object) - Optional - Extension point for implementations.
*   **`fs`** (object) - Optional - File system capability. This property likely references a `FileSystemCapability` interface which is not detailed here.
*   **`terminal`** (boolean) - Optional - Whether the Client supports all `terminal/*` methods.
```

--------------------------------

### New Session Request Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/NewSessionRequest

Defines the structure for requests to create a new agent session, including working directory and MCP server configurations.

```APIDOC
## Interface NewSessionRequest

### Description
Request parameters for creating a new session. Refer to the protocol documentation for more details on creating a session.

### Method
POST (Implied, as it's a request to create a new resource)

### Endpoint
/sessions (Assumed endpoint for creating a new session)

### Parameters
#### Request Body
- **_meta** (_object_) - Optional - Extension point for implementations.
- **cwd** (_string_) - Required - The working directory for this session. Must be an absolute path.
- **mcpServers** (_array of McpServer_) - Required - List of MCP (Model Context Protocol) servers the agent should connect to.

### Request Example
```json
{
  "cwd": "/path/to/working/directory",
  "mcpServers": [
    {
      "host": "mcp.example.com",
      "port": 8080
    }
  ]
}
```

### Response
#### Success Response (200 or 201)
- **sessionId** (_string_) - The unique identifier for the newly created session.
- **status** (_string_) - The status of the session creation.

#### Response Example
```json
{
  "sessionId": "abc123xyz789",
  "status": "session_created"
}
```
```

--------------------------------

### PromptCapabilities Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/PromptCapabilities

The PromptCapabilities interface defines the optional boolean flags indicating support for various content types within the Agent Client Protocol.

```APIDOC
## PromptCapabilities

### Description
Prompt capabilities supported by the agent.

### Interface Definition
```typescript
interface PromptCapabilities {
  _meta?: { [k: string]: unknown };
  audio?: boolean;
  embeddedContext?: boolean;
  image?: boolean;
}
```

### Properties

#### `_meta`
- **Type**: `{ [k: string]: unknown }`
- **Optional**: Yes
- **Description**: Extension point for implementations.

#### `audio`
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Agent supports [`ContentBlock::Audio`].

#### `embeddedContext`
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Agent supports embedded context in `session/prompt` requests. When enabled, the Client is allowed to include [`ContentBlock::Resource`] in prompt requests for pieces of context that are referenced in the message.

#### `image`
- **Type**: `boolean`
- **Optional**: Yes
- **Description**: Agent supports [`ContentBlock::Image`].
```

--------------------------------

### Agent Initialization Method (TypeScript)

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Agent

Details the 'initialize' method for the Agent interface. This method is used to establish a connection, negotiate protocol versions, exchange capabilities, and determine authentication methods.

```TypeScript
initialize(params: InitializeRequest): Promise<InitializeResponse>;
/**
Establishes the connection with a client and negotiates protocol capabilities.
This method is called once at the beginning of the connection to:
    * Negotiate the protocol version to use
    * Exchange capability information between client and agent
    * Determine available authentication methods
The agent should respond with its supported protocol version and capabilities.
See protocol docs: Initialization
*/
```

--------------------------------

### InitializeRequest

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/InitializeRequest

Represents the request sent by the client to initialize a connection and negotiate capabilities with the server.

```APIDOC
## InitializeRequest

### Description
Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities. See protocol docs: Initialization.

### Method
(Not specified, typically POST for initialization)

### Endpoint
(Not specified)

### Parameters
#### Request Body
- **_meta** (object) - Optional - Extension point for implementations
- **clientCapabilities** (object) - Optional - Client capabilities
- **protocolVersion** (number) - Required - The latest protocol version supported by the client.

### Request Example
```json
{
  "_meta": {},
  "clientCapabilities": {},
  "protocolVersion": 1
}
```

### Response
#### Success Response (200)
(Not specified in the provided text)

#### Response Example
(Not specified in the provided text)
```

--------------------------------

### Plan Object

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/SessionNotification

Represents the agent's plan, consisting of a list of plan entries that define the tasks to be accomplished.

```APIDOC
## Type Declaration: Plan

### Description
Represents the agent's execution plan, detailing the sequence of tasks.

### Properties
- **_meta** (object) - Optional. Extension point for implementations.
- **entries** (PlanEntry[]) - The list of tasks to be accomplished. When updating a plan, the agent must send a complete list of all entries with their current status. The client replaces the entire plan with each update.
- **sessionUpdate** (string) - The type of session update. Must be `plan`.
```

--------------------------------

### Content Blocks for Tool Calls (TypeScript)

Source: https://zed-industries.github.io/agent-client-protocol/types/ToolCallContent

Illustrates specific content block types within the Agent Client Protocol, including text, images, audio, resource links, and terminal output.

```typescript
{
  content: {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    text: string;
    type: "text";
  };
}
```

```typescript
{
  content: {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    data: string;
    mimeType: string;
    type: "image";
    uri?: string | null;
  };
}
```

```typescript
{
  content: {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    data: string;
    mimeType: string;
    type: "audio";
  };
}
```

```typescript
{
  content: {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    description?: string | null;
    mimeType?: string | null;
    name: string;
    size?: number | null;
    title?: string | null;
    type: "resource_link";
    uri: string;
  };
}
```

```typescript
{
  content: {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    resource: EmbeddedResourceResource;
    type: "resource";
  };
}
```

```typescript
{
  _meta?: { [k: string]: unknown };
  newText: string;
  oldText?: string | null;
  path: string;
  type: "diff";
}
```

```typescript
{
  terminalId: string;
  type: "terminal";
}
```

--------------------------------

### FileSystemCapability Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/FileSystemCapability

Defines the file system capabilities supported by the client, determining which file operations the agent can request.

```APIDOC
## Interface FileSystemCapability

File system capabilities supported by the client. Determines which file operations the agent can request.

### Properties

#### `Optional` _meta
- **Type**: `{ [k: string]: unknown }`
- **Description**: Extension point for implementations.

#### `Optional` readTextFile
- **Type**: `boolean`
- **Description**: Whether the Client supports `fs/read_text_file` requests.

#### `Optional` writeTextFile
- **Type**: `boolean`
- **Description**: Whether the Client supports `fs/write_text_file` requests.

```

--------------------------------

### CreateTerminalRequest

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/CreateTerminalRequest

Request to create a new terminal and execute a command.

```APIDOC
## POST /terminals

### Description
Creates a new terminal and executes a command within that terminal.

### Method
POST

### Endpoint
/terminals

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute.
- **sessionId** (string) - Required - The session ID for this request.
- **args** (string[]) - Optional - Array of command arguments.
- **cwd** (string | null) - Optional - Working directory for the command (absolute path).
- **env** (EnvVariable[]) - Optional - Environment variables for the command.
- **outputByteLimit** (number | null) - Optional - Maximum number of output bytes to retain.
- **_meta** ({ [k: string]: unknown }) - Optional - Extension point for implementations

### Request Example
```json
{
  "command": "ls -la",
  "sessionId": "your-session-id",
  "args": ["-l", "-a"],
  "cwd": "/home/user",
  "env": [
    {"name": "MY_VAR", "value": "my_value"}
  ],
  "outputByteLimit": 1024,
  "_meta": {
    "custom_key": "custom_value"
  }
}
```

### Response
#### Success Response (201 Created)
- **terminalId** (string) - The ID of the newly created terminal.
- **sessionId** (string) - The session ID associated with the terminal.

#### Response Example
```json
{
  "terminalId": "term-12345",
  "sessionId": "your-session-id"
}
```

#### Error Response (400 Bad Request)
- **error** (string) - Description of the error.

#### Error Response Example
```json
{
  "error": "Invalid command provided."
}
```
```

--------------------------------

### Define CLIENT_METHODS in JavaScript

Source: https://zed-industries.github.io/agent-client-protocol/variables/CLIENT_METHODS

This snippet defines the CLIENT_METHODS object, which maps method names to their corresponding protocol strings. These methods cover file system operations, session management, and terminal control.

```javascript
CLIENT_METHODS: {
 fs_read_text_file: "fs/read_text_file";
 fs_write_text_file: "fs/write_text_file";
 session_request_permission: "session/request_permission";
 session_update: "session/update";
 terminal_create: "terminal/create";
 terminal_kill: "terminal/kill";
 terminal_output: "terminal/output";
 terminal_release: "terminal/release";
 terminal_wait_for_exit: "terminal/wait_for_exit";
}
```

--------------------------------

### PromptRequest Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/PromptRequest

Defines the request parameters for sending a user prompt to the agent, including the user's message and additional context.

```APIDOC
## Interface PromptRequest

### Description
Request parameters for sending a user prompt to the agent. Contains the user's message and any additional context.

### Properties

#### `_meta`
* **Type:** `{ [k: string]: unknown }`
* **Optional:** Yes
* **Description:** Extension point for implementations.

#### `prompt`
* **Type:** `ContentBlock[]`
* **Required:** Yes
* **Description:** The blocks of content that compose the user's message. The Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`], while other variants are optionally enabled via [`PromptCapabilities`]. The client MUST adapt its interface according to [`PromptCapabilities`]. The client MAY include referenced pieces of context as either [`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`]. When available, [`ContentBlock::Resource`] is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to.

#### `sessionId`
* **Type:** `string`
* **Required:** Yes
* **Description:** The ID of the session to send this user message to.

### Example Request Body
```json
{
  "prompt": [
    {
      "type": "text",
      "content": "Hello, agent!"
    }
  ],
  "sessionId": "user-session-123"
}
```

### Example Success Response (200)
```json
{
  "response": "Acknowledged. How can I help you?"
}
```
```

--------------------------------

### CreateTerminalRequest Interface Definition

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/CreateTerminalRequest

Defines the structure for a request to create a new terminal and execute a command. It includes optional and required fields such as the command to run, arguments, working directory, environment variables, output byte limit, and session ID. The `_meta` field serves as an extension point.

```typescript
interface CreateTerminalRequest {
 _meta?: { [k: string]: unknown };
 args?: string[];
 command: string;
 cwd?: null | string;
 env?: EnvVariable[];
 outputByteLimit?: null | number;
 sessionId: string;
}
```

--------------------------------

### Agent Prompt Method (TypeScript)

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Agent

Details the 'prompt' method for processing user prompts within a session. It covers the lifecycle from receiving user messages and context to executing tool calls and completing the turn.

```TypeScript
prompt(params: PromptRequest): Promise<PromptResponse>;
/**
Processes a user prompt within a session.
This method handles the whole lifecycle of a prompt:
    * Receives user messages with optional context (files, images, etc.)
    * Processes the prompt using language models
    * Reports language model content and tool calls to the Clients
    * Requests permission to run tools
    * Executes any requested tool calls
    * Returns when the turn is complete with a stop reason
See protocol docs: Prompt Turn
*/
```

--------------------------------

### AgentCapabilities Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/AgentCapabilities

Details the structure and properties of the AgentCapabilities interface, outlining the various capabilities an agent might support.

```APIDOC
## AgentCapabilities

### Description
Capabilities supported by the agent.

### Interface
```typescript
interface AgentCapabilities {
  _meta?: { [k: string]: unknown };
  loadSession?: boolean;
  mcpCapabilities?: McpCapabilities;
  promptCapabilities?: PromptCapabilities;
}
```

### Properties

*   **_meta** (`{ [k: string]: unknown }`): Optional. Extension point for implementations.
*   **loadSession** (`boolean`): Optional. Whether the agent supports `session/load`.
*   **mcpCapabilities** (`McpCapabilities`): Optional. Specifies the MCP capabilities.
*   **promptCapabilities** (`PromptCapabilities`): Optional. Specifies the prompt capabilities.
```

--------------------------------

### Agent Interface - extMethod

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Agent

Allows calling arbitrary external methods on the agent.

```APIDOC
## POST /extMethod

### Description
Allows calling arbitrary external methods on the agent. This is used for custom or extended functionality not covered by the standard protocol.

### Method
POST

### Endpoint
/extMethod

### Parameters
#### Request Body
- **method** (string) - Required - The name of the external method to call.
- **params** (Record<string, unknown>) - Required - Parameters for the external method.

### Response
#### Success Response (200)
- **Record<string, unknown>** - The result of the external method call.

#### Response Example
```json
{
  "result": "operation successful"
}
```
```

--------------------------------

### Interface Stdio

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Stdio

Configuration for the Stdio transport, which all Agents must support. This interface defines the parameters needed to launch and configure an MCP server using stdio.

```APIDOC
## Interface Stdio

### Description
Stdio transport configuration. All Agents MUST support this transport.

### Properties

#### args
- **Type**: string[]
- **Description**: Command-line arguments to pass to the MCP server.

#### command
- **Type**: string
- **Description**: Path to the MCP server executable.

#### env
- **Type**: EnvVariable[]
- **Description**: Environment variables to set when launching the MCP server.

#### name
- **Type**: string
- **Description**: Human-readable name identifying this MCP server.
```

--------------------------------

### McpServer Configuration

Source: https://zed-industries.github.io/agent-client-protocol/types/McpServer

Defines the configuration for connecting to an MCP server, which provides tools and context for agents.

```APIDOC
## McpServer Configuration Type

### Description
Configuration for connecting to an MCP (Model Context Protocol) server. MCP servers provide tools and context that the agent can use when processing prompts.

### Type Declaration

McpServer can be one of the following:

1.  **HTTP Server Configuration**
    ```json
    {
      "headers": HttpHeader[],
      "name": string,
      "type": "http",
      "url": string
    }
    ```
    *   **headers** (HttpHeader[]) - HTTP headers to set when making requests to the MCP server.
    *   **name** (string) - Human-readable name identifying this MCP server.
    *   **type** (string) - Must be "http".
    *   **url** (string) - URL to the MCP server.

2.  **SSE Server Configuration**
    ```json
    {
      "headers": HttpHeader[],
      "name": string,
      "type": "sse",
      "url": string
    }
    ```
    *   **headers** (HttpHeader[]) - HTTP headers to set when making requests to the MCP server.
    *   **name** (string) - Human-readable name identifying this MCP server.
    *   **type** (string) - Must be "sse".
    *   **url** (string) - URL to the MCP server.

3.  **Stdio Configuration**
    ```json
    Stdio
    ```
    *   Represents a Server-Sent Events (SSE) connection.

### Settings

*   **Member Visibility**: Inherited, External
*   **Theme**: OS, Light, Dark

### Example Request (HTTP)
```json
{
  "headers": [
    {"name": "Authorization", "value": "Bearer YOUR_TOKEN"}
  ],
  "name": "MyHttpMCPServer",
  "type": "http",
  "url": "http://localhost:8080/mcp"
}
```

### Example Request (SSE)
```json
{
  "headers": [
    {"name": "Accept", "value": "text/event-stream"}
  ],
  "name": "MySseMCPServer",
  "type": "sse",
  "url": "http://localhost:8081/stream"
}
```
```

--------------------------------

### Annotations Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Annotations

Defines optional annotations for the client to inform object usage or display.

```APIDOC
## Interface Annotations

### Description
Optional annotations for the client. The client can use annotations to inform how objects are used or displayed.

### Properties

#### `_meta`
- **Type**: `{ [k: string]: unknown }`
- **Optional**: Yes
- **Description**: Extension point for implementations.

#### `audience`
- **Type**: `null | Role[]`
- **Optional**: Yes

#### `lastModified`
- **Type**: `null | string`
- **Optional**: Yes

#### `priority`
- **Type**: `null | number`
- **Optional**: Yes
```

--------------------------------

### createTerminal

Source: https://zed-industries.github.io/agent-client-protocol/classes/AgentSideConnection

Executes a command in a new terminal and returns a `TerminalHandle` for control.

```APIDOC
## POST /createTerminal

### Description
Executes a command in a new terminal. Returns a `TerminalHandle` that can be used to get output, wait for exit, kill the command, or release the terminal. The terminal can also be embedded in tool calls by using its ID in `ToolCallContent` with type "terminal".

### Method
POST

### Endpoint
/createTerminal

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **params** (CreateTerminalRequest) - Required - The terminal creation parameters.

### Request Example
```json
{
  "params": {}
}
```

### Response
#### Success Response (200)
- **response** (TerminalHandle) - A handle to control and monitor the terminal.

#### Response Example
```json
{
  "response": {}
}
```
```

--------------------------------

### RequestError Constructor

Source: https://zed-industries.github.io/agent-client-protocol/classes/RequestError

Initializes a new instance of the RequestError class with a code, message, and optional data.

```typescript
new RequestError(code: number, message: string, data?: unknown): RequestError
```

--------------------------------

### extMethod Method (Optional)

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Client

Handles extension-specific method calls from the agent. Allows for custom communication between the agent and client extensions.

```typescript
extMethod?(
method: string,
params: Record<string, unknown>,
): Promise<Record<string, unknown>>
```

--------------------------------

### Client Interface - createTerminal

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Client

Creates a new terminal. Only available if the `terminal` capability is set to `true`.

```APIDOC
## POST /client/createTerminal

### Description
Creates a new terminal to execute a command. Only available if the `terminal` capability is set to `true`. The Agent must call `releaseTerminal` when done with the terminal to free resources.

### Method
POST

### Endpoint
/client/createTerminal

### Parameters
#### Request Body
- **params** (CreateTerminalRequest) - Required - The request parameters for creating a terminal.

### Request Example
```json
{
  "params": {
    "command": "ls -l",
    "cwd": "/app"
  }
}
```

### Response
#### Success Response (200)
- **terminalId** (string) - The ID of the created terminal.

#### Response Example
```json
{
  "terminalId": "term-abc-123"
}
```
```

--------------------------------

### Process User Prompt with Agent

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Processes a user prompt within a session, handling the full lifecycle from receiving messages to tool execution. It manages language model processing, reports content and tool calls, requests permissions, executes tools, and returns the completion status.

```typescript
prompt(params: PromptRequest): Promise<PromptResponse>
```

--------------------------------

### Stdio Interface Properties

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Stdio

Details the properties of the Stdio interface, explaining their purpose and data types. These include command-line arguments, the server executable path, environment variables, and a unique name for the MCP server.

```typescript
args: string[]
Command-line arguments to pass to the MCP server.
```

```typescript
command: string
Path to the MCP server executable.
```

```typescript
env: EnvVariable[]
Environment variables to set when launching the MCP server.
```

```typescript
name: string
Human-readable name identifying this MCP server.
```

--------------------------------

### Define NewSessionRequest Interface (TypeScript)

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/NewSessionRequest

Defines the structure of the NewSessionRequest, used for initiating a new agent session. It includes optional metadata, the current working directory, and a list of MCP servers.

```TypeScript
interface NewSessionRequest {
  _meta?: { [k: string]: unknown };
  cwd: string;
  mcpServers: McpServer[];
}
```

--------------------------------

### Available Commands Update Object

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/SessionNotification

Informs the client about the commands currently available to the agent.

```APIDOC
## Type Declaration: AvailableCommandsUpdate

### Description
Notifies the client about the set of commands the agent can currently execute.

### Properties
- **availableCommands** (AvailableCommand[]) - A list of commands the agent can use.
- **sessionUpdate** (string) - The type of session update. Must be `available_commands_update`.
```

--------------------------------

### Agent Interface - prompt

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Agent

Processes a user prompt within a session, handling the entire lifecycle from receiving messages to executing tool calls.

```APIDOC
## POST /prompt

### Description
Processes a user prompt within a session. This method handles the full lifecycle of a prompt: receiving user messages, processing with language models, reporting content and tool calls, requesting permissions, executing tools, and returning when the turn is complete.

### Method
POST

### Endpoint
/prompt

### Parameters
#### Request Body
- **params** (PromptRequest) - Required - The prompt request parameters, including messages and context.

### Response
#### Success Response (200)
- **PromptResponse** (object) - The response from the agent after processing the prompt.

#### Response Example
```json
{
  "content": [
    { "type": "text", "text": "Here's the generated code." }
  ],
  "stopReason": "end_turn"
}
```
```

--------------------------------

### ClientSideConnection Constructor

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Creates a new client-side connection to an agent, establishing the communication channel using the ACP specification.

```APIDOC
## Constructor ClientSideConnection

### Description
Creates a new client-side connection to an agent. This establishes the communication channel between a client and agent following the ACP specification.

### Method
CONSTRUCTOR

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Client Interface - writeTextFile

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Client

Writes content to a text file. Only available if the client advertises the `fs.writeTextFile` capability.

```APIDOC
## POST /client/writeTextFile

### Description
Writes content to a text file in the client's file system. Only available if the client advertises the `fs.writeTextFile` capability. Allows the agent to create or modify files within the client's environment.

### Method
POST

### Endpoint
/client/writeTextFile

### Parameters
#### Request Body
- **params** (WriteTextFileRequest) - Required - The request parameters for writing a text file.

### Request Example
```json
{
  "params": {
    "filePath": "/path/to/newfile.txt",
    "content": "This is the file content."
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the file write operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### AuthMethod Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/AuthMethod

Defines the structure for an available authentication method, including its ID, name, and optional description and metadata.

```APIDOC
## Interface AuthMethod

Describes an available authentication method.

### Properties

- **`_meta`** (_meta?: { [k: string]: unknown }) - Optional - Extension point for implementations.
- **`description`** (description?: null | string) - Optional - Optional description providing more details about this authentication method.
- **`id`** (id: string) - Required - Unique identifier for this authentication method.
- **`name`** (name: string) - Required - Human-readable name of the authentication method.

### Example Request Body (Illustrative)

```json
{
  "id": "auth-method-123",
  "name": "API Key",
  "description": "Authenticate using a provided API key.",
  "_meta": {
    "version": "1.0"
  }
}
```

### Example Success Response (Illustrative)

```json
{
  "id": "auth-method-123",
  "name": "API Key",
  "description": "Authenticate using a provided API key.",
  "_meta": {
    "version": "1.0"
  }
}
```
```

--------------------------------

### POST /prompt

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Processes a user prompt within a session, handling the entire lifecycle of a prompt turn.

```APIDOC
## POST /prompt

### Description
Processes a user prompt within a session. This method handles the whole lifecycle of a prompt: receiving user messages, processing the prompt, reporting content and tool calls, requesting permission, executing tools, and returning when the turn is complete.

### Method
POST

### Endpoint
/prompt

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **params** (PromptRequest) - Required - The prompt request details.

### Request Example
```json
{
  "params": {
    "sessionId": "session-12345",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **response** (PromptResponse) - The agent's response to the prompt.

#### Response Example
```json
{
  "response": {
    "messages": [
      {
        "role": "assistant",
        "content": "The capital of France is Paris."
      }
    ],
    "stopReason": "endturn"
  }
}
```
```

--------------------------------

### PlanEntry Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/PlanEntry

Defines the structure of a single entry in the execution plan, representing a task or goal for an assistant.

```APIDOC
## Interface PlanEntry

A single entry in the execution plan. Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user's request.

### Properties

*   **_meta** (_meta?: { [k: string]: unknown }) - Optional - Extension point for implementations.
*   **content** (string) - Required - Human-readable description of what this task aims to accomplish.
*   **priority** ("high" | "medium" | "low") - Required - The relative importance of this task. Used to indicate which tasks are most critical to the overall goal.
*   **status** ("pending" | "in_progress" | "completed") - Required - Current execution status of this task.

### Request Example

```json
{
  "_meta": {
    "custom_field": "value"
  },
  "content": "Write a blog post about the new features.",
  "priority": "high",
  "status": "pending"
}
```

### Response Example

```json
{
  "_meta": {
    "custom_field": "value"
  },
  "content": "Write a blog post about the new features.",
  "priority": "high",
  "status": "pending"
}
```
```

--------------------------------

### requestPermission Method

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/Client

Handles requests for user permission for tool call operations. The client must present options to the user and return their decision. It must respond with `RequestPermissionOutcome::Cancelled` if the client cancels the prompt turn via `session/cancel`.

```typescript
requestPermission(
params: RequestPermissionRequest,
): Promise<RequestPermissionResponse>
```

--------------------------------

### AgentSideConnection Constructor

Source: https://zed-industries.github.io/agent-client-protocol/classes/AgentSideConnection

Creates a new agent-side connection to a client, establishing the communication channel from the agent's perspective following the ACP specification.

```APIDOC
## AgentSideConnection Constructor

### Description
Creates a new agent-side connection to a client. This establishes the communication channel from the agent's perspective following the ACP specification.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Interface AvailableCommand

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/AvailableCommand

Represents information about a command available to the agent client.

```APIDOC
## Interface AvailableCommand

### Description
Information about a command.

### Properties

#### `Optional` _meta
- **Type**: `{ [k: string]: unknown }`
- **Description**: Extension point for implementations.

#### description
- **Type**: `string`
- **Description**: Human-readable description of what the command does.

#### `Optional` input
- **Type**: `null | UnstructuredCommandInput`
- **Description**: Input for the command if required.

#### name
- **Type**: `string`
- **Description**: Command name (e.g., `create_plan`, `research_codebase`).
```

--------------------------------

### BlobResourceContents Interface

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/BlobResourceContents

Describes the structure of binary resource contents, including metadata, the blob data, MIME type, and URI.

```APIDOC
## BlobResourceContents

### Description
Binary resource contents.

### Interface Definition
```typescript
interface BlobResourceContents {
  _meta?: { [k: string]: unknown };
  blob: string;
  mimeType?: null | string;
  uri: string;
}
```

### Properties

#### `_meta`
- **Type**: `{ [k: string]: unknown }`
- **Optional**: Yes
- **Description**: Extension point for implementations.

#### `blob`
- **Type**: `string`
- **Required**: Yes
- **Description**: The binary resource content, likely base64 encoded.

#### `mimeType`
- **Type**: `null | string`
- **Optional**: Yes
- **Description**: The MIME type of the resource.

#### `uri`
- **Type**: `string`
- **Required**: Yes
- **Description**: The Uniform Resource Identifier for the resource.
```

--------------------------------

### POST /loadSession

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Loads an existing session to resume a previous conversation, streaming the entire conversation history back to the client.

```APIDOC
## POST /loadSession

### Description
Loads an existing session to resume a previous conversation. This method is only available if the agent advertises the `loadSession` capability. The agent should restore the session context and conversation history, and stream the entire conversation history back to the client via notifications.

### Method
POST

### Endpoint
/loadSession

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **params** (LoadSessionRequest) - Required - Parameters for loading an existing session.

### Request Example
```json
{
  "params": {
    "sessionId": "session-12345"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the session was loaded.

#### Response Example
```json
{
  "message": "Session session-12345 loaded successfully."
}
```
```

--------------------------------

### Interface FileSystemCapability Definition

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/FileSystemCapability

Defines the file system capabilities supported by the client. This interface determines which file operations the agent can request, including reading and writing text files.

```typescript
interface FileSystemCapability {
  _meta?: { [k: string]: unknown };
  readTextFile?: boolean;
  writeTextFile?: boolean;
}
```

--------------------------------

### Create New Session with Agent

Source: https://zed-industries.github.io/agent-client-protocol/classes/ClientSideConnection

Creates a new conversation session with the agent. Sessions represent independent conversation contexts. The agent creates a new session context, connects to specified MCP servers, and returns a unique session ID. May return an `auth_required` error if authentication is needed.

```typescript
newSession(params: NewSessionRequest): Promise<NewSessionResponse>
```

--------------------------------

### ContentBlock Type Definitions - TypeScript

Source: https://zed-industries.github.io/agent-client-protocol/types/ContentBlock

Defines the structure for various content block types including text, image, audio, resource_link, and resource. Each type has optional metadata and annotations, with specific fields relevant to its content.

```typescript
type ContentBlock = |
  {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    text: string;
    type: "text";
  }
  |
  {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    data: string;
    mimeType: string;
    type: "image";
    uri?: string | null;
  }
  |
  {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    data: string;
    mimeType: string;
    type: "audio";
  }
  |
  {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    description?: string | null;
    mimeType?: string | null;
    name: string;
    size?: number | null;
    title?: string | null;
    type: "resource_link";
    uri: string;
  }
  |
  {
    _meta?: { [k: string]: unknown };
    annotations?: Annotations | null;
    resource: EmbeddedResourceResource;
    type: "resource";
  };
```

--------------------------------

### Tool Call Type Declaration (TypeScript)

Source: https://zed-industries.github.io/agent-client-protocol/interfaces/SessionNotification

Defines the structure for initiating a tool call. It includes metadata, content, the type of operation, locations, raw input/output, the session update type, status, title, and a unique tool call ID.

```typescript
{
  _meta?: { [k: string]: unknown };
  content?: ToolCallContent[];
  kind?: "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "switch_mode" | "other";
  locations?: ToolCallLocation[];
  rawInput?: { [k: string]: unknown };
  rawOutput?: { [k: string]: unknown };
  sessionUpdate: "tool_call";
  status?: "pending" | "in_progress" | "completed" | "failed";
  title: string;
  toolCallId: string;
}
```
Tokens:
Raw