Agent Client Protocol - v1.2.1
    Preparing search index...

    Interface Agent

    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.

    interface Agent {
        initialize(params: InitializeRequest): MaybePromise<InitializeResponse>;
        newSession(params: NewSessionRequest): MaybePromise<NewSessionResponse>;
        loadSession?(
            params: LoadSessionRequest,
        ): MaybePromise<void | LoadSessionResponse>;
        unstable_forkSession?(
            params: ForkSessionRequest,
        ): MaybePromise<ForkSessionResponse>;
        listSessions?(
            params: ListSessionsRequest,
        ): MaybePromise<ListSessionsResponse>;
        deleteSession?(
            params: DeleteSessionRequest,
        ): MaybePromise<void | DeleteSessionResponse>;
        resumeSession?(
            params: ResumeSessionRequest,
        ): MaybePromise<ResumeSessionResponse>;
        closeSession?(
            params: CloseSessionRequest,
        ): MaybePromise<void | CloseSessionResponse>;
        setSessionMode?(
            params: SetSessionModeRequest,
        ): MaybePromise<void | SetSessionModeResponse>;
        setSessionConfigOption?(
            params: SetSessionConfigOptionRequest,
        ): MaybePromise<SetSessionConfigOptionResponse>;
        authenticate(
            params: AuthenticateRequest,
        ): MaybePromise<void | AuthenticateResponse>;
        unstable_listProviders?(
            params: ListProvidersRequest,
        ): MaybePromise<ListProvidersResponse>;
        unstable_setProvider?(
            params: SetProviderRequest,
        ): MaybePromise<void | SetProviderResponse>;
        unstable_disableProvider?(
            params: DisableProviderRequest,
        ): MaybePromise<void | DisableProviderResponse>;
        logout?(params: LogoutRequest): MaybePromise<void | LogoutResponse>;
        prompt(params: PromptRequest): MaybePromise<PromptResponse>;
        cancel(params: CancelNotification): MaybePromise<void>;
        unstable_startNes?(params: StartNesRequest): MaybePromise<StartNesResponse>;
        unstable_suggestNes?(
            params: SuggestNesRequest,
        ): MaybePromise<SuggestNesResponse>;
        unstable_closeNes?(
            params: CloseNesRequest,
        ): MaybePromise<void | CloseNesResponse>;
        unstable_didOpenDocument?(
            params: DidOpenDocumentNotification,
        ): MaybePromise<void>;
        unstable_didChangeDocument?(
            params: DidChangeDocumentNotification,
        ): MaybePromise<void>;
        unstable_didCloseDocument?(
            params: DidCloseDocumentNotification,
        ): MaybePromise<void>;
        unstable_didSaveDocument?(
            params: DidSaveDocumentNotification,
        ): MaybePromise<void>;
        unstable_didFocusDocument?(
            params: DidFocusDocumentNotification,
        ): MaybePromise<void>;
        unstable_acceptNes?(params: AcceptNesNotification): MaybePromise<void>;
        unstable_rejectNes?(params: RejectNesNotification): MaybePromise<void>;
        extMethod?(
            method: string,
            params: Record<string, unknown>,
        ): MaybePromise<Record<string, unknown>>;
        extNotification?(
            method: string,
            params: Record<string, unknown>,
        ): MaybePromise<void>;
    }

    Implemented by

    Index
    initialize newSession loadSession? unstable_forkSession? listSessions? deleteSession? resumeSession? closeSession? setSessionMode? setSessionConfigOption? authenticate unstable_listProviders? unstable_setProvider? unstable_disableProvider? logout? prompt cancel unstable_startNes? unstable_suggestNes? unstable_closeNes? unstable_didOpenDocument? unstable_didChangeDocument? unstable_didCloseDocument? unstable_didSaveDocument? unstable_didFocusDocument? unstable_acceptNes? unstable_rejectNes? extMethod? extNotification?

    • 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

      The request may include additionalDirectories to expand the session's filesystem scope beyond cwd without changing the base for relative paths.

      May return an auth_required error if the agent requires authentication.

      See protocol docs: Session Setup

      Parameters

      Returns MaybePromise<NewSessionResponse>

    • 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

      The request may include additionalDirectories to set the complete list of additional workspace roots for the loaded session.

      See protocol docs: Loading Sessions

      Parameters

      Returns MaybePromise<void | LoadSessionResponse>

    • Experimental

      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.

      The request may include additionalDirectories to set the complete list of additional workspace roots for the forked session.

      This method is only available if the agent advertises the session.fork capability.

      Parameters

      Returns MaybePromise<ForkSessionResponse>

    • 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).

      The request may include additionalDirectories to set the complete list of additional workspace roots for the resumed session.

      Parameters

      Returns MaybePromise<ResumeSessionResponse>

    • 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

      Parameters

      Returns MaybePromise<void | SetSessionModeResponse>

    • 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

      Parameters

      Returns MaybePromise<PromptResponse>

    • 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

      Parameters

      Returns MaybePromise<void>

    • Handles a request that is not otherwise registered by the legacy agent.

      Allows the Client 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.

      Parameters

      • method: string
      • params: Record<string, unknown>

      Returns MaybePromise<Record<string, unknown>>

      Prefer agent().onRequest(...) for custom methods.

    • Handles a notification that is not otherwise registered by the legacy agent.

      Allows the Client to send an arbitrary notification that is not part of the ACP spec.

      Parameters

      • method: string
      • params: Record<string, unknown>

      Returns MaybePromise<void>

      Prefer agent().onNotification(...) for custom notifications.

    Settings
    Member Visibility

    On This Page
    Methods