Creates a new agent-side connection to a client.
This establishes the communication channel from the agent's perspective following the ACP specification.
A function that creates an Agent handler to process incoming client requests
The bidirectional message stream for communication. Typically created using ndJsonStream for stdio-based connections.
See protocol docs: Communication Model
AbortSignal that aborts when the connection closes.
This signal can be used to:
connection.signal.addEventListener('abort', () => {...})if (connection.signal.aborted) {...}The connection closes when the underlying stream ends, either normally or due to an error.
const connection = new AgentSideConnection(agent, stream);
// Listen for closure
connection.signal.addEventListener('abort', () => {
console.log('Connection closed - performing cleanup');
});
// Check status
if (connection.signal.aborted) {
console.log('Connection is already closed');
}
// Pass to other APIs
fetch(url, { signal: connection.signal });
Promise that resolves when the connection closes.
The connection closes when the underlying stream ends, either normally or due to an error. Once closed, the connection cannot send or receive any more messages.
This is useful for async/await style cleanup:
Handles session update notifications from the agent.
This is a notification endpoint (no response expected) that sends 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.
See protocol docs: Agent Reports Output
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.
See protocol docs: Requesting Permission
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.
See protocol docs: Client
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.
See protocol docs: Client
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".
The terminal creation parameters
A handle to control and monitor the terminal
Experimental
UNSTABLE
This capability is not part of the spec yet, and may be removed or changed at any point.
Creates an elicitation to request input from the user.
Experimental
UNSTABLE
This capability is not part of the spec yet, and may be removed or changed at any point.
Notifies the client that a URL-based elicitation is complete.
Sends a request to the client by ACP method name.
Built-in method literals infer their params and response types. Custom methods can specify their response and params types with generics.
Optionaloptions: SendRequestOptionsSends a request to the client by ACP method name.
Built-in method literals infer their params and response types. Custom methods can specify their response and params types with generics.
Optionalparams: ParamsOptionaloptions: SendRequestOptionsSends a notification to the client by ACP method name.
Built-in method literals infer their params type. Custom notifications can specify their params type with a generic.
Sends a notification to the client by ACP method name.
Built-in method literals infer their params type. Custom notifications can specify their params type with a generic.
Optionalparams: ParamsExtension method.
Use request.
Extension notification.
Use notify.
An agent-side connection to a client.
This class provides the agent's view of an ACP connection, allowing agents to communicate with clients. It implements the Client interface to provide methods for requesting permissions, accessing the file system, and sending session updates.
See protocol docs: Agent
Deprecated
Prefer agent, which registers typed handlers with a single context object and supports direct app composition.