ACPex.Agent behaviour (ACPex v0.1.0)

Behaviour for implementing an ACP agent (AI coding assistant).

An agent is responsible for:

Handling initialization and authentication
Managing conversation sessions
Processing user prompts and generating responses
Making requests to the client for file and terminal operations

Type-Safe API

All callbacks use strongly-typed structs from the ACPex.Schema.* modules, providing compile-time validation and better documentation.

Example

defmodule MyAgent do
  @behaviour ACPex.Agent

  def init(_args), do: {:ok, %{}}

  def handle_initialize(request, state) do
    response = %ACPex.Schema.Connection.InitializeResponse{
      protocol_version: 1,
      agent_capabilities: %{sessions: %{new: true}}
    }
    {:ok, response, state}
  end

  def handle_new_session(request, state) do
    response = %ACPex.Schema.Session.NewResponse{}
    {:ok, response, state}
  end

  # ... other callbacks
end

Summary

Types

error_response()

state()

Callbacks

handle_authenticate(t, state)

Handle authentication request from the client.

handle_cancel(t, state)

Handle a cancellation request for an ongoing prompt.

handle_initialize(t, state)

Handle the initialization handshake from the client.

handle_load_session(map, state)

Handle loading of an existing session.

handle_new_session(t, state)

Handle creation of a new session (conversation).

handle_prompt(t, state)

Handle a user prompt within a session.

init(args)

Initialize the agent with the given arguments.

Types

error_response()

@type error_response() :: %{code: integer(), message: String.t()}

state()

@type state() :: term()

Callbacks

handle_authenticate(t, state)

@callback handle_authenticate(ACPex.Schema.Connection.AuthenticateRequest.t(), state()) ::
  {:ok, ACPex.Schema.Connection.AuthenticateResponse.t(), state()}
  | {:error, error_response(), state()}

Handle authentication request from the client.

Parameters

request - An AuthenticateRequest struct
state - Current agent state

Returns

{:ok, response, new_state} where response is an AuthenticateResponse struct
{:error, error_map, new_state} for authentication failures

handle_cancel(t, state)

@callback handle_cancel(ACPex.Schema.Session.CancelNotification.t(), state()) ::
  {:noreply, state()}

Handle a cancellation request for an ongoing prompt.

Parameters

notification - A CancelNotification struct
state - Current agent state

Returns

{:noreply, new_state} - No response is sent for cancellations

handle_initialize(t, state)

@callback handle_initialize(ACPex.Schema.Connection.InitializeRequest.t(), state()) ::
  {:ok, ACPex.Schema.Connection.InitializeResponse.t(), state()}

Handle the initialization handshake from the client.

This is where capabilities are negotiated.

Parameters

request - An InitializeRequest struct with protocol version and client capabilities
state - Current agent state

Returns

{:ok, response, new_state} where response is an InitializeResponse struct

handle_load_session(map, state)

@callback handle_load_session(map(), state()) ::
  {:ok, map(), state()} | {:error, error_response(), state()}

Handle loading of an existing session.

Parameters

request - A session load request struct
state - Current agent state

Returns

{:ok, response, new_state} on successful load
{:error, error_map, new_state} if session not found

handle_new_session(t, state)

@callback handle_new_session(ACPex.Schema.Session.NewRequest.t(), state()) ::
  {:ok, ACPex.Schema.Session.NewResponse.t(), state()}

Handle creation of a new session (conversation).

Parameters

request - A NewRequest struct
state - Current agent state

Returns

{:ok, response, new_state} where response is a NewResponse struct

handle_prompt(t, state)

@callback handle_prompt(ACPex.Schema.Session.PromptRequest.t(), state()) ::
  {:ok, ACPex.Schema.Session.PromptResponse.t(), state()}

Handle a user prompt within a session.

The agent should process the prompt and send updates via ACPex.Protocol.Connection.send_notification/3.

Parameters

request - A PromptRequest struct with session_id and prompt content
state - Current agent state

Returns

{:ok, response, new_state} where response is a PromptResponse struct

init(args)

@callback init(args :: term()) :: {:ok, state()}

Initialize the agent with the given arguments.

Returns {:ok, initial_state}.