Skip to main content

​
Overview

The Client interface defines the interface that ACP-compliant clients must implement. Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources.

​
Type Definition

export interface Client {
  // Required methods
  requestPermission(
    params: RequestPermissionRequest
  ): Promise<RequestPermissionResponse>;
  sessionUpdate(params: SessionNotification): Promise<void>;
  
  // Optional methods
  writeTextFile?(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
  readTextFile?(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
  createTerminal?(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
  terminalOutput?(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
  releaseTerminal?(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse | void>;
  waitForTerminalExit?(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
  killTerminal?(params: KillTerminalRequest): Promise<KillTerminalResponse | void>;
  extMethod?(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
  extNotification?(method: string, params: Record<string, unknown>): Promise<void>;
}

​
Required Methods

​
requestPermission

requestPermission(
  params: RequestPermissionRequest
): Promise<RequestPermissionResponse>
Requests permission from the user for a tool call operation. Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision. If the client cancels the prompt turn via session/cancel, it MUST respond to this request with RequestPermissionOutcome::Cancelled.
​
params
RequestPermissionRequest
required
The permission request parameters
​
response
RequestPermissionResponse
The user’s permission decision
See protocol docs: Requesting Permission

​
sessionUpdate

sessionUpdate(params: SessionNotification): Promise<void>
Handles session update notifications from the agent. This is a notification endpoint (no response expected) that receives real-time updates about session progress, including message chunks, tool calls, and execution plans. Note: Clients SHOULD continue accepting tool call updates even after sending a session/cancel notification, as the agent may send final updates before responding with the cancelled stop reason.
​
params
SessionNotification
required
The session notification parameters containing updates about session progress
​
Promise<void>
Promise<void>
A promise that resolves when the notification has been processed
See protocol docs: Agent Reports Output

​
Optional Methods

​
writeTextFile

writeTextFile?(params: WriteTextFileRequest): Promise<WriteTextFileResponse>
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.
​
params
WriteTextFileRequest
required
The file write request parameters
​
response
WriteTextFileResponse
An empty object on success
See protocol docs: Client

​
readTextFile

readTextFile?(params: ReadTextFileRequest): Promise<ReadTextFileResponse>
Reads content from a text file in the client’s file system. Only available if the client advertises the fs.readTextFile capability. Allows the agent to access file contents within the client’s environment.
​
params
ReadTextFileRequest
required
The file read request parameters
​
response
ReadTextFileResponse
The file contents
See protocol docs: Client

​
createTerminal

createTerminal?(params: CreateTerminalRequest): Promise<CreateTerminalResponse>
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.
​
params
CreateTerminalRequest
required
The terminal creation parameters
​
response
CreateTerminalResponse
The terminal ID
See Terminal Documentation

​
terminalOutput

terminalOutput?(params: TerminalOutputRequest): Promise<TerminalOutputResponse>
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.
​
params
TerminalOutputRequest
required
The terminal output request parameters
​
response
TerminalOutputResponse
The current terminal output and exit status (if available)
See Getting Terminal Output

​
releaseTerminal

releaseTerminal?(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse | void>
Releases a terminal and frees all associated resources. The command is killed if it hasn’t exited yet. After release, the terminal ID becomes invalid for all other terminal methods. Tool calls that already contain the terminal ID continue to display its output.
​
params
ReleaseTerminalRequest
required
The release terminal request parameters
​
response
ReleaseTerminalResponse | void
An empty object on success, or void
See Releasing Terminals

​
waitForTerminalExit

waitForTerminalExit?(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>
Waits for a terminal command to exit and returns its exit status. This method returns once the command completes, providing the exit code and/or signal that terminated the process.
​
params
WaitForTerminalExitRequest
required
The wait for exit request parameters
​
response
WaitForTerminalExitResponse
The exit status of the terminal command
See Waiting for Exit

​
killTerminal

killTerminal?(params: KillTerminalRequest): Promise<KillTerminalResponse | void>
Kills a terminal command without releasing the terminal. While releaseTerminal also kills the command, this method keeps the terminal ID valid so it can be used with other methods. Useful for implementing command timeouts that terminate the command and then retrieve the final output. Note: Call releaseTerminal when the terminal is no longer needed.
​
params
KillTerminalRequest
required
The kill terminal request parameters
​
response
KillTerminalResponse | void
An empty object on success, or void
See Killing Commands

​
extMethod

extMethod?(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>
Extension method. Allows the Agent to send an arbitrary request that is not part of the ACP spec. To help avoid conflicts, it’s a good practice to prefix extension methods with a unique identifier such as domain name.
​
method
string
required
The extension method name
​
params
Record<string, unknown>
required
The extension method parameters
​
response
Record<string, unknown>
The extension method response

​
extNotification

extNotification?(method: string, params: Record<string, unknown>): Promise<void>
Extension notification. Allows the Agent to send an arbitrary notification that is not part of the ACP spec.
​
method
string
required
The extension notification name
​
params
Record<string, unknown>
required
The extension notification parameters
​
Promise<void>
Promise<void>
A promise that resolves when the notification has been processed

Build docs developers (and LLMs) love

Get started for freeTalk to us