Agentix.Conversation (Agentix v0.1.0)

Copy Markdown View Source

The public entry points for driving a conversation.

ensure_started/2 is the only addressing point: it returns the live agent (via Agentix.Registry) or starts and rehydrates one under Agentix.ConversationSupervisor. Both new messages and resolutions enter through it, so a conversation killed mid-flight is revived transparently on the next call.

A conversation is single-in-flight: a send_message/3 while a turn is running returns {:error, :busy}.

Summary

Types

message()

A user message — plain text or a prebuilt ReqLLM.Message.

Functions

cancel(conversation_id)

Cancels the in-flight turn from any non-idle state. A no-op if not running.

ensure_started(conversation_id, opts \\ [])

Returns the running agent for conversation_id, starting one if absent.

send_message(conversation_id, message, scope, opts \\ [])

Sends a user message to the conversation under scope, starting the agent if needed (pass config: in opts for a new conversation). Returns :ok once the turn is accepted, or {:error, :busy} if a turn is already in flight.

Types

message()

@type message() :: String.t() | ReqLLM.Message.t()

A user message — plain text or a prebuilt ReqLLM.Message.

Functions

cancel(conversation_id)

@spec cancel(String.t()) :: :ok

Cancels the in-flight turn from any non-idle state. A no-op if not running.

ensure_started(conversation_id, opts \\ [])

@spec ensure_started(
  String.t(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Returns the running agent for conversation_id, starting one if absent.

For a brand-new conversation pass config: %Agentix.Conversation.Config{}. On revival the config is rebuilt from the persisted settings, so :config may be omitted; without either, {:error, :unknown_conversation} is returned.

send_message(conversation_id, message, scope, opts \\ [])

@spec send_message(String.t(), message(), Agentix.Scope.t(), keyword()) ::
  :ok | {:error, term()}

Sends a user message to the conversation under scope, starting the agent if needed (pass config: in opts for a new conversation). Returns :ok once the turn is accepted, or {:error, :busy} if a turn is already in flight.