Agentic.Protocol.ACP.Session (agentic v0.2.2)

ACP session lifecycle management.

Manages the full ACP connection lifecycle:

initialize -- negotiate protocol version and capabilities
authenticate -- if agent requires authentication
session/new -- create a new conversation session
session/prompt -- send user messages, collect streaming updates
session/cancel -- cancel an ongoing prompt turn
Cleanup -- close connection gracefully

Usage

{:ok, session} = Agentic.Protocol.ACP.Session.connect(
  client: acp_client,
  workspace: "/path/to/project",
  permission_policy: :ask
)

{:ok, response, session} = Agentic.Protocol.ACP.Session.prompt(
  session,
  [%{"type" => "text", "text" => "Hello"}]
)

:ok = Agentic.Protocol.ACP.Session.cancel(session)
:ok = Agentic.Protocol.ACP.Session.close(session)

Summary

Types

session()

Functions

can_load_session?(session)

Check if the agent supports session loading.

cancel(session, opts)

Cancel the current prompt turn.

close(session, opts)

Close the session and stop the client.

connect(opts)

Connect to an ACP agent: initialize, authenticate (if needed), create session.

load(session, session_id)

Load an existing session by ID.

prompt(session, content_blocks, opts)

Send a prompt to the agent and collect the response.

set_mode(session, mode_id)

Switch the agent operating mode.

supports_audio?(session)

Check if the agent supports audio input.

supports_image?(session)

Check if the agent supports image input.

Types

session()

@type session() :: %Agentic.Protocol.ACP.Session{
  agent_capabilities: map() | nil,
  agent_info: map() | nil,
  client: pid(),
  mcp_servers: [map()],
  permission_policy: atom(),
  prompt_accumulator: String.t(),
  protocol_version: pos_integer() | nil,
  session_id: String.t() | nil,
  updates: [map()],
  workspace: String.t()
}

Functions

can_load_session?(session)

@spec can_load_session?(session()) :: boolean()

Check if the agent supports session loading.

cancel(session, opts)

@spec cancel(
  session(),
  keyword()
) :: :ok

Cancel the current prompt turn.

close(session, opts)

@spec close(
  session(),
  keyword()
) :: :ok

Close the session and stop the client.

connect(opts)

@spec connect(keyword()) :: {:ok, session()} | {:error, term()}

Connect to an ACP agent: initialize, authenticate (if needed), create session.

Options

:client - ACP Client pid (required)
:workspace - Working directory for the session (required)
:permission_policy - :ask, :allow_all, or :deny_all (default :ask)
:mcp_servers - List of MCP server configs to forward (default [])
:client_info - Override client info sent during initialize
:client_capabilities - Override client capabilities

load(session, session_id)

@spec load(session(), String.t()) :: {:ok, session()} | {:error, term()}

Load an existing session by ID.

Only works if the agent advertised loadSession: true during initialize.

prompt(session, content_blocks, opts)

@spec prompt(session(), [Agentic.Protocol.ACP.Types.content_block()], keyword()) ::
  {:ok, map(), session()} | {:error, term()}

Send a prompt to the agent and collect the response.

Returns {:ok, response, session} where response contains:

:content - accumulated text content
:tool_calls - list of tool calls made during the turn
:stop_reason - why the agent stopped
:updates - all raw session/update notifications received

set_mode(session, mode_id)

@spec set_mode(session(), String.t()) :: :ok | {:error, term()}

Switch the agent operating mode.

supports_audio?(session)

@spec supports_audio?(session()) :: boolean()

Check if the agent supports audio input.

supports_image?(session)

@spec supports_image?(session()) :: boolean()

Check if the agent supports image input.