A behaviour and supervision framework for long-running LLM agent processes, modeled as OTP state machines.

Each agent is a :gen_statem process wrapping a persistent LLM session. Every interaction is a prompt-response turn, and the implementation decides what happens between turns.

It is a GenServer but every call is a prompt.

GenAgent handles the mechanics of turns. Implementations handle the semantics of turns.

Installation

def deps do
  [
    {:gen_agent, "~> 0.1.0"},
    # Plus at least one backend:
    {:gen_agent_claude, "~> 0.1.0"},
    {:gen_agent_codex, "~> 0.1.0"}
  ]
end

Quick start

defmodule MyApp.Coder do
  use GenAgent

  defmodule State do
    defstruct [:path, responses: []]
  end

  @impl true
  def init_agent(opts) do
    path = Keyword.fetch!(opts, :cwd)

    backend_opts = [
      cwd: path,
      system_prompt: "You are a coding assistant."
    ]

    {:ok, backend_opts, %State{path: path}}
  end

  @impl true
  def handle_response(_ref, response, state) do
    {:noreply, %{state | responses: state.responses ++ [response.text]}}
  end
end

# Start the agent under the GenAgent supervision tree.
{:ok, _pid} = GenAgent.start_agent(MyApp.Coder,
  name: "my-coder",
  backend: GenAgent.Backends.Claude,
  cwd: "/path/to/project"
)

# Synchronous prompt.
{:ok, response} = GenAgent.ask("my-coder", "What does lib/foo.ex do?")
IO.puts(response.text)

# Async prompt.
{:ok, ref} = GenAgent.tell("my-coder", "Add tests for lib/foo.ex")
{:ok, :completed, response} = GenAgent.poll("my-coder", ref)

# External event.
GenAgent.notify("my-coder", {:ci_failed, "test_auth"})

GenAgent.stop("my-coder")

State model

An agent is a state machine with two states:

idle --- ask/tell/notify ---> processing
                                  |
                                  v
idle <--- handle_response --- processing (turn done)

Self-chaining: handle_response/3 can return {:prompt, text, state} to immediately dispatch another turn without a caller, useful for multi-step work that the agent drives itself.

Halting: any callback can return {:halt, state} to go idle but freeze the mailbox. A halted agent ignores queued prompts until resume/1 is called.

Backends

Backends implement GenAgent.Backend and translate the LLM-specific wire protocol into the normalized GenAgent.Event stream the state machine consumes. Available backends (in sibling packages):

• GenAgent.Backends.Claude (package: gen_agent_claude) -- wraps the Anthropic claude CLI via ClaudeWrapper.
• GenAgent.Backends.Codex (package: gen_agent_codex) -- wraps the OpenAI codex CLI via CodexWrapper.

A backend owns its session lifecycle, translates events, and carries any state it needs (session id, message history) in an opaque session term.

Callbacks

• init_agent/1 -- set up backend options and initial agent state.
• handle_response/3 -- a turn completed, decide what to do next.
• handle_error/3 (optional) -- a turn failed, decide what to do next.
• handle_event/2 (optional) -- an external event arrived via notify/2.
• handle_stream_event/2 (optional) -- a backend event arrived mid-turn. Runs inside the prompt task, not the agent process.
• terminate_agent/2 (optional) -- the agent is shutting down.

Lifecycle hooks (all optional):

• pre_run/1 -- one-time setup after init_agent, before the first turn.
• pre_turn/2 -- before each dispatch. Can rewrite the prompt, skip, or halt.
• post_turn/3 -- after each turn, post-decision. For state-mutating side effects.
• post_run/1 -- on clean {:halt, state} from any callback. For completion side effects.

The use GenAgent macro provides default implementations of the optional callbacks and lifecycle hooks.

Public API

• start_agent/2 -- start an agent under the supervision tree.
• ask/3 -- synchronous prompt, blocks until the turn finishes.
• tell/3 -- async prompt, returns a ref for poll/3.
• poll/3 -- check on a previously-issued tell/3.
• notify/2 -- push an external event into handle_event/2.
• interrupt/1 -- cancel an in-flight turn.
• resume/1 -- unhalt an agent and drain its mailbox.
• status/2 -- read the agent's current state.
• stop/1 -- terminate the agent.
• whereis/1 -- look up an agent's pid.

Data types

• GenAgent.Event -- a normalized event emitted by a backend during a turn.
• GenAgent.Response -- the result of a completed turn delivered to handle_response/3.

Telemetry

GenAgent emits telemetry events for observability:

• [:gen_agent, :prompt, :start | :stop | :error]

• [:gen_agent, :event, :received]
• [:gen_agent, :state, :changed]
• [:gen_agent, :mailbox, :queued]
• [:gen_agent, :halted]

What GenAgent does not do

• It does not prescribe agent behavior (no retry logic, no summary format).
• It does not prescribe inter-agent communication (agents can notify/2 each other but the message format is up to you).
• It does not manage persistence across restarts.
• It does not manage cost tracking or budgets.

See GenAgent.Backend for the backend behaviour, GenAgent.Event and GenAgent.Response for the data types delivered to callbacks.