Skip to main content

​
Overview

The Agent interface defines the interface that all ACP-compliant agents must implement. Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools.

​
Type Definition

export interface Agent {
  // Required methods
  initialize(params: InitializeRequest): Promise<InitializeResponse>;
  newSession(params: NewSessionRequest): Promise<NewSessionResponse>;
  authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse | void>;
  prompt(params: PromptRequest): Promise<PromptResponse>;
  cancel(params: CancelNotification): Promise<void>;
  
  // Optional methods
  loadSession?(params: LoadSessionRequest): Promise<LoadSessionResponse>;
  unstable_forkSession?(params: ForkSessionRequest): Promise<ForkSessionResponse>;
  unstable_listSessions?(params: ListSessionsRequest): Promise<ListSessionsResponse>;
  unstable_resumeSession?(params: ResumeSessionRequest): Promise<ResumeSessionResponse>;
  setSessionMode?(params: SetSessionModeRequest): Promise<SetSessionModeResponse | void>;
  unstable_setSessionModel?(params: SetSessionModelRequest): Promise<SetSessionModelResponse | void>;
  setSessionConfigOption?(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
  extMethod?(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
  extNotification?(method: string, params: Record<string, unknown>): Promise<void>;
}

​
Required Methods

​
initialize

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.
​
params
InitializeRequest
required
The initialization request parameters
​
response
InitializeResponse
The agent’s capabilities and protocol version
See protocol docs: Initialization

​
newSession

newSession(params: NewSessionRequest): Promise<NewSessionResponse>
Creates a new conversation session with the agent. Sessions represent independent conversation contexts with their own history and state. The agent should:
  • Create a new session context
  • Connect to any specified MCP servers
  • Return a unique session ID for future requests
May return an auth_required error if the agent requires authentication.
​
params
NewSessionRequest
required
The new session request parameters
​
response
NewSessionResponse
The new session information including session ID
See protocol docs: Session Setup

​
authenticate

authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse | void>
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.
​
params
AuthenticateRequest
required
The authentication request parameters
​
response
AuthenticateResponse | void
An empty object on success, or void
See protocol docs: Initialization

​
prompt

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
​
params
PromptRequest
required
The prompt request parameters
​
response
PromptResponse
The prompt response with stop reason
See protocol docs: Prompt Turn

​
cancel

cancel(params: CancelNotification): Promise<void>
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:
  • Stop all language model requests as soon as possible
  • Abort all tool call invocations in progress
  • Send any pending session/update notifications
  • Respond to the original session/prompt request with StopReason::Cancelled
​
params
CancelNotification
required
The cancellation notification parameters
​
Promise<void>
Promise<void>
A promise that resolves when the notification has been processed
See protocol docs: Cancellation

​
Optional Methods

​
loadSession

loadSession?(params: LoadSessionRequest): Promise<LoadSessionResponse>
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
  • Connect to the specified MCP servers
  • Stream the entire conversation history back to the client via notifications
​
params
LoadSessionRequest
required
The load session request parameters
​
response
LoadSessionResponse
An empty object on success
See protocol docs: Loading Sessions

​
unstable_forkSession

unstable_forkSession?(params: ForkSessionRequest): Promise<ForkSessionResponse>
UNSTABLE - This capability is not part of the spec yet, and may be removed or changed at any point. Forks an existing session to create a new independent session. Creates a new session based on the context of an existing one, allowing operations like generating summaries without affecting the original session’s history. This method is only available if the agent advertises the session.fork capability.
​
params
ForkSessionRequest
required
The fork session request parameters
​
response
ForkSessionResponse
The forked session information

​
unstable_listSessions

unstable_listSessions?(params: ListSessionsRequest): Promise<ListSessionsResponse>
UNSTABLE - This capability is not part of the spec yet, and may be removed or changed at any point. Lists existing sessions from the agent. This method is only available if the agent advertises the listSessions capability. Returns a list of sessions with metadata like session ID, working directory, title, and last update time. Supports filtering by working directory and cursor-based pagination.
​
params
ListSessionsRequest
required
The list sessions request parameters
​
response
ListSessionsResponse
The list of sessions with metadata

​
unstable_resumeSession

unstable_resumeSession?(params: ResumeSessionRequest): Promise<ResumeSessionResponse>
UNSTABLE - This capability is not part of the spec yet, and may be removed or changed at any point. Resumes an existing session without returning previous messages. This method is only available if the agent advertises the session.resume capability. The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike session/load).
​
params
ResumeSessionRequest
required
The resume session request parameters
​
response
ResumeSessionResponse
The resumed session information

​
setSessionMode

setSessionMode?(params: SetSessionModeRequest): Promise<SetSessionModeResponse | void>
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.
​
params
SetSessionModeRequest
required
The set session mode request parameters
​
response
SetSessionModeResponse | void
An empty object on success, or void
See protocol docs: Session Modes

​
unstable_setSessionModel

unstable_setSessionModel?(params: SetSessionModelRequest): Promise<SetSessionModelResponse | void>
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.
​
params
SetSessionModelRequest
required
The set session model request parameters
​
response
SetSessionModelResponse | void
An empty object on success, or void

​
setSessionConfigOption

setSessionConfigOption?(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>
Set a configuration option for a given session. The response contains the full set of configuration options and their current values, as changing one option may affect the available values or state of other options.
​
params
SetSessionConfigOptionRequest
required
The set config option request parameters
​
response
SetSessionConfigOptionResponse
The full set of configuration options and their current values

​
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