Watcher

Reactive event-driven agent. Starts idle with no initial prompt and sits waiting until events are pushed at it via GenAgent.notify/2. handle_event/2 filters events -- interesting ones dispatch a turn, boring ones no-op.

When to reach for this

The agent exists to react to an external signal stream, not to drive work on its own. CI status changes, PR events, file system changes, scheduled triggers, webhook deliveries, queue arrivals. The "decide when to do something" is outside the agent -- the agent's job is just to decide what to do with each event as it lands.

This is the only pattern in the collection where the agent has no initial turn at all. GenAgent.start_agent/2 returns, the agent sits in :idle, and it stays there until notify/2 is called.

What it exercises in gen_agent

• handle_event/2 as the primary trigger mechanism -- all dispatches come through notify, never through ask/2 or tell/2 from the manager.
• Event filtering via pattern matching -- one handle_event/2 clause per interesting event shape plus a catchall returning {:noreply, state}.
• Idle-until-triggered: no initial tell/2 call, no self-chain, no phase machine. The agent is a pure reducer over incoming events.
• handle_event returning {:prompt, text, state} to turn an interesting event into a dispatched turn.

State mutation caveat (pre-v0.2)

On gen_agent v0.1, handle_event/2 state mutations could be silently overwritten by an in-flight turn's handle_response state. That was fixed in the notify-deferral patch (v0.1.1): events arriving during :processing are buffered into pending_events and drained synchronously against post-decision state before the transition to :idle.

If you're on gen_agent v0.1.1 or later, you can mutate state from handle_event/2 freely. The example below is conservative and only mutates state from handle_response/3, which still works as a style choice if you want a single place for state writes.

The pattern

One callback module. The manager never sends prompts directly; everything is driven by notify/2.

defmodule Watcher.Agent do
  @moduledoc """
  A reactive GenAgent that starts idle and only wakes up when
  interesting events arrive.

  Events this agent understands:
    * {:ci_result, :passed}             -- ignored
    * {:ci_result, :failed, details}    -- diagnosis turn
    * {:pr_opened, author, title}       -- welcome turn
    * {:timer, label}                   -- ignored
  """

  use GenAgent

  defmodule State do
    defstruct actions: []
  end

  @impl true
  def init_agent(opts) do
    system = """
    You are a CI/PR watcher. When asked to diagnose a build
    failure, respond in 2 short sentences: likely cause +
    suggested first step. When asked to welcome a PR, respond in
    one sentence. No preamble.
    """

    {:ok, [system: system, max_tokens: Keyword.get(opts, :max_tokens, 120)], %State{}}
  end

  # --- Event filtering ---

  @impl true
  def handle_event({:ci_result, :passed}, state), do: {:noreply, state}

  def handle_event({:ci_result, :failed, details}, state) do
    prompt = """
    CI build failed with this error:

    #{details}

    Diagnose the likely cause and first debugging step.
    """

    {:prompt, prompt, state}
  end

  def handle_event({:pr_opened, author, title}, state) do
    prompt = ~s|#{author} just opened a PR titled: "#{title}". Welcome them in one sentence.|
    {:prompt, prompt, state}
  end

  def handle_event({:timer, _label}, state), do: {:noreply, state}

  def handle_event(_other, state), do: {:noreply, state}

  # --- Turn completion ---

  @impl true
  def handle_response(_ref, response, %State{} = state) do
    action = %{text: String.trim(response.text), at: System.system_time(:millisecond)}
    {:noreply, %{state | actions: state.actions ++ [action]}}
  end
end

Using it

{:ok, _pid} = GenAgent.start_agent(Watcher.Agent,
  name: "ci-watcher",
  backend: GenAgent.Backends.Anthropic
)

# No initial turn. The agent is idle.
GenAgent.status("ci-watcher")
# => %{state: :idle, queued: 0, ...}

# Push events.
GenAgent.notify("ci-watcher", {:ci_result, :passed})
# -> ignored, agent stays idle

GenAgent.notify("ci-watcher", {:pr_opened, "alice", "fix: auth header bug"})
# -> dispatches a welcome turn

GenAgent.notify("ci-watcher", {:ci_result, :failed, "test_auth.ex:42: assertion failed"})
# -> dispatches a diagnosis turn

# Read the log of actions the agent has produced.
%{agent_state: %{actions: actions}} = GenAgent.status("ci-watcher")
Enum.each(actions, fn a -> IO.puts(a.text) end)

GenAgent.stop("ci-watcher")

Variations

• External signal sources. Hook a GenServer or a Task that tails GitHub webhooks, inotify, a Kafka topic, or a cron-style scheduler, and have it call GenAgent.notify/2 on every event. The watcher doesn't care where events come from.
• Routing to multiple watchers. If you want different watchers for different event classes, start N named watchers and have the dispatcher pattern-match events to routes.
• Rate limiting. If the event stream is bursty, the watcher's mailbox can fill up. Drop-on-busy at the notify source, or use handle_event({:ci_result, :failed, _}, %{recent: ts}) with a state-tracked cooldown.
• Combine with Pool. A single watcher can receive events and GenAgent.tell/2 them into a worker pool for parallel processing. The watcher becomes pure dispatch logic; the pool does the work.
• Self-destructing watcher. A watcher that halts itself after receiving N events or after a certain time, so you can start short-lived scoped watchers for narrow windows of interest.