Creates a new client-side connection to an agent.
This establishes the communication channel between a client and agent following the ACP specification.
A function that creates a Client handler to process incoming agent requests
The bidirectional message stream for communication. Typically created using ndJsonStream for stdio-based connections.
See protocol docs: Communication Model
Establishes the connection with a client and negotiates protocol capabilities.
This method is called once at the beginning of the connection to:
The agent should respond with its supported protocol version and capabilities.
See protocol docs: Initialization
Creates a new conversation session with the agent.
Sessions represent independent conversation contexts with their own history and state.
The agent should:
May return an auth_required error if the agent requires authentication.
See protocol docs: Session Setup
Loads an existing session to resume a previous conversation.
This method is only available if the agent advertises the loadSession capability.
The agent should:
See protocol docs: Loading Sessions
Sets the operational mode for a session.
Allows switching between different agent modes (e.g., "ask", "architect", "code") that affect system prompts, tool availability, and permission behaviors.
The mode must be one of the modes advertised in availableModes during session
creation or loading. Agents may also change modes autonomously and notify the
client via current_mode_update notifications.
This method can be called at any time during a session, whether the Agent is idle or actively generating a turn.
See protocol docs: Session Modes
UNSTABLE
This capability is not part of the spec yet, and may be removed or changed at any point.
Select a model for a given session.
Authenticates the client using the specified authentication method.
Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization.
After successful authentication, the client can proceed to create sessions with
newSession without receiving an auth_required error.
See protocol docs: Initialization
Processes a user prompt within a session.
This method handles the whole lifecycle of a prompt:
See protocol docs: Prompt Turn
Cancels ongoing operations for a session.
This is a notification sent by the client to cancel an ongoing prompt turn.
Upon receiving this notification, the Agent SHOULD:
session/update notificationssession/prompt request with StopReason::CancelledSee protocol docs: Cancellation
Extension method
Allows the Client to send an arbitrary request that is not part of the ACP spec.
Extension notification
Allows the Client to send an arbitrary notification that is not part of the ACP spec.
A client-side connection to an agent.
This class provides the client's view of an ACP connection, allowing clients (such as code editors) to communicate with agents. It implements the Agent interface to provide methods for initializing sessions, sending prompts, and managing the agent lifecycle.
See protocol docs: Client