Trait Agent 

pub trait Agent {
    // Required methods
    fn initialize<'life0, 'async_trait>(
        &'life0 self,
        args: InitializeRequest,
    ) -> Pin<Box<dyn Future<Output = Result<InitializeResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn authenticate<'life0, 'async_trait>(
        &'life0 self,
        args: AuthenticateRequest,
    ) -> Pin<Box<dyn Future<Output = Result<AuthenticateResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn new_session<'life0, 'async_trait>(
        &'life0 self,
        args: NewSessionRequest,
    ) -> Pin<Box<dyn Future<Output = Result<NewSessionResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn prompt<'life0, 'async_trait>(
        &'life0 self,
        args: PromptRequest,
    ) -> Pin<Box<dyn Future<Output = Result<PromptResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn cancel<'life0, 'async_trait>(
        &'life0 self,
        args: CancelNotification,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn load_session<'life0, 'async_trait>(
        &'life0 self,
        _args: LoadSessionRequest,
    ) -> Pin<Box<dyn Future<Output = Result<LoadSessionResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn set_session_mode<'life0, 'async_trait>(
        &'life0 self,
        _args: SetSessionModeRequest,
    ) -> Pin<Box<dyn Future<Output = Result<SetSessionModeResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn ext_method<'life0, 'async_trait>(
        &'life0 self,
        _args: ExtRequest,
    ) -> Pin<Box<dyn Future<Output = Result<ExtResponse, Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn ext_notification<'life0, 'async_trait>(
        &'life0 self,
        _args: ExtNotification,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

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.

Required Methods

fn initialize<'life0, 'async_trait>( &'life0 self, args: InitializeRequest, ) -> Pin<Box<dyn Future<Output = Result<InitializeResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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

fn authenticate<'life0, 'async_trait>( &'life0 self, args: AuthenticateRequest, ) -> Pin<Box<dyn Future<Output = Result<AuthenticateResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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 new_session without receiving an auth_required error.

See protocol docs: Initialization

fn new_session<'life0, 'async_trait>( &'life0 self, args: NewSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<NewSessionResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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.

See protocol docs: Session Setup

fn prompt<'life0, 'async_trait>( &'life0 self, args: PromptRequest, ) -> Pin<Box<dyn Future<Output = Result<PromptResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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

fn cancel<'life0, 'async_trait>( &'life0 self, args: CancelNotification, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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

See protocol docs: Cancellation

Provided Methods

fn load_session<'life0, 'async_trait>( &'life0 self, _args: LoadSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<LoadSessionResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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

See protocol docs: Loading Sessions

fn set_session_mode<'life0, 'async_trait>( &'life0 self, _args: SetSessionModeRequest, ) -> Pin<Box<dyn Future<Output = Result<SetSessionModeResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Sets the current 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 response.

See protocol docs: Session Modes

fn ext_method<'life0, 'async_trait>( &'life0 self, _args: ExtRequest, ) -> Pin<Box<dyn Future<Output = Result<ExtResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handles extension method requests from the client.

Extension methods provide a way to add custom functionality while maintaining protocol compatibility.

See protocol docs: Extensibility

fn ext_notification<'life0, 'async_trait>( &'life0 self, _args: ExtNotification, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Handles extension notifications from the client.

Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility.

See protocol docs: Extensibility

Implementations on Foreign Types

impl<T: Agent> Agent for Rc<T>

fn initialize<'life0, 'async_trait>( &'life0 self, args: InitializeRequest, ) -> Pin<Box<dyn Future<Output = Result<InitializeResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn authenticate<'life0, 'async_trait>( &'life0 self, args: AuthenticateRequest, ) -> Pin<Box<dyn Future<Output = Result<AuthenticateResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn new_session<'life0, 'async_trait>( &'life0 self, args: NewSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<NewSessionResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn load_session<'life0, 'async_trait>( &'life0 self, args: LoadSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<LoadSessionResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn set_session_mode<'life0, 'async_trait>( &'life0 self, args: SetSessionModeRequest, ) -> Pin<Box<dyn Future<Output = Result<SetSessionModeResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn prompt<'life0, 'async_trait>( &'life0 self, args: PromptRequest, ) -> Pin<Box<dyn Future<Output = Result<PromptResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn cancel<'life0, 'async_trait>( &'life0 self, args: CancelNotification, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn ext_method<'life0, 'async_trait>( &'life0 self, args: ExtRequest, ) -> Pin<Box<dyn Future<Output = Result<ExtResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn ext_notification<'life0, 'async_trait>( &'life0 self, args: ExtNotification, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

impl<T: Agent> Agent for Arc<T>

fn initialize<'life0, 'async_trait>( &'life0 self, args: InitializeRequest, ) -> Pin<Box<dyn Future<Output = Result<InitializeResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn authenticate<'life0, 'async_trait>( &'life0 self, args: AuthenticateRequest, ) -> Pin<Box<dyn Future<Output = Result<AuthenticateResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn new_session<'life0, 'async_trait>( &'life0 self, args: NewSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<NewSessionResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn load_session<'life0, 'async_trait>( &'life0 self, args: LoadSessionRequest, ) -> Pin<Box<dyn Future<Output = Result<LoadSessionResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn set_session_mode<'life0, 'async_trait>( &'life0 self, args: SetSessionModeRequest, ) -> Pin<Box<dyn Future<Output = Result<SetSessionModeResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn prompt<'life0, 'async_trait>( &'life0 self, args: PromptRequest, ) -> Pin<Box<dyn Future<Output = Result<PromptResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn cancel<'life0, 'async_trait>( &'life0 self, args: CancelNotification, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn ext_method<'life0, 'async_trait>( &'life0 self, args: ExtRequest, ) -> Pin<Box<dyn Future<Output = Result<ExtResponse, Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn ext_notification<'life0, 'async_trait>( &'life0 self, args: ExtNotification, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Implementors

impl Agent for ClientSideConnection