GenServer wrapper for Nous agents with PubSub integration.

This server:

• Wraps a Nous agent (standard or ReAct)
• Links to parent process (dies when parent dies)
• Subscribes to PubSub for incoming messages
• Publishes responses back via PubSub
• Maintains conversation context for multi-turn conversations

Context-Based State

Uses Nous.Agent.Context to maintain conversation state:

• Messages accumulate across turns
• Tool calls are tracked
• Usage is aggregated
• Callbacks forward to PubSub

Usage with LiveView

defmodule MyAppWeb.ChatLive do
  use MyAppWeb, :live_view

  def mount(_params, _session, socket) do
    # Start agent linked to this LiveView
    {:ok, agent_pid} = AgentServer.start_link(
      session_id: socket.assigns.session_id,
      agent_config: %{
        model: "lmstudio:qwen3-vl-4b-thinking-mlx",
        instructions: "You are a helpful assistant",
        tools: []
      }
    )

    # Subscribe to responses
    Phoenix.PubSub.subscribe(MyApp.PubSub, "agent:#{socket.assigns.session_id}")

    {:ok, assign(socket, agent_pid: agent_pid, messages: [])}
  end

  def handle_event("send_message", %{"message" => msg}, socket) do
    AgentServer.send_message(socket.assigns.agent_pid, msg)
    {:noreply, socket}
  end

  # Receive streaming deltas
  def handle_info({:agent_delta, text}, socket) do
    # Append text to current response
    {:noreply, update(socket, :current_response, &(&1 <> text))}
  end

  # Receive complete response
  def handle_info({:agent_complete, result}, socket) do
    messages = socket.assigns.messages ++ [%{role: :assistant, content: result.output}]
    {:noreply, assign(socket, messages: messages, current_response: "")}
  end

  # Receive tool calls
  def handle_info({:tool_call, call}, socket) do
    # Show tool call in UI
    {:noreply, socket}
  end
end

Message Interruption

Calling send_message/2 while the agent is already processing a request automatically cancels the in-flight execution and starts a new one. The server uses an :atomics-based flag so the running task can detect cancellation without message-passing overhead. Both the interrupted user message and the new one are preserved in the conversation context, so no input is lost.

PubSub Events

Subscribers on the "agent:<session_id>" topic receive the following messages:

Lifecycle

Each server starts an inactivity timer (default 5 minutes, configurable via :inactivity_timeout). The timer resets on every send_message/2 call. When the timer fires, the server terminates with :normal.

If a :persistence backend is configured, the conversation context is automatically saved after each successful agent run and restored on start_link/1.