Checkpointer

Human-in-the-loop review workflow. The agent works on a multi-step task autonomously, but after each step sits idle with a phase marker instead of halting, waiting for the manager to send one of approve, {:revise, hint}, or finish.

When to reach for this

You want an agent to produce draft work in steps, but a human (or a reviewing agent) needs to gate each step before the next one starts. Writing a document one paragraph at a time with review between paragraphs. Producing a release plan and approving each stage. Generating PR descriptions that need human sign-off before posting.

The critical design decision is not to halt. If you halt with {:halt, state} to pause for review, you freeze the mailbox -- which means a subsequent {:prompt, ..., state} return from handle_event/2 will silently enqueue but never dispatch. Idle with a phase marker is the correct primitive for "wait for next input from outside."

What it exercises in gen_agent

• Idle-with-phase-marker as a pause primitive. handle_response/3 returns {:noreply, state} with phase: :awaiting_review instead of {:halt, state}. The agent is idle and its mailbox is live, so a subsequent notify/2 can dispatch the next turn.
• handle_event/2 returning {:prompt, text, state} as a resume primitive. Each review decision produces the next prompt and transitions back to :drafting.
• Multiple decision outcomes from the manager: approve (continue to next step), revise (redo with feedback), finish (halt).
• Terminal halt only happens on final approval or explicit finish -- not on intermediate pauses.

The pattern

One callback module. The manager's review decisions come in as {:review, :approve | {:revise, feedback} | :finish} notifies.

defmodule Checkpointer.Agent do
  use GenAgent

  defmodule State do
    defstruct [
      :task,
      :draft,
      :current_step,
      :total_steps,
      phase: :drafting,
      history: [],
      feedback: nil
    ]
  end

  @impl true
  def init_agent(opts) do
    state = %State{
      task: Keyword.fetch!(opts, :task),
      current_step: 1,
      total_steps: Keyword.get(opts, :total_steps, 3)
    }

    system = """
    You are a writing assistant working on a multi-step task.
    Each turn, produce one refinement of the current draft. Keep
    each output concise. No preamble, no explanations -- just
    the draft.
    """

    {:ok, [system: system, max_tokens: Keyword.get(opts, :max_tokens, 300)], state}
  end

  @impl true
  def handle_response(_ref, response, %State{} = state) do
    draft = String.trim(response.text)

    new_history =
      state.history ++ [%{step: state.current_step, draft: draft, feedback: state.feedback}]

    new_state = %{
      state
      | draft: draft,
        history: new_history,
        feedback: nil,
        phase: :awaiting_review
    }

    # NOT {:halt, state} -- halt would freeze the mailbox and
    # block handle_event's {:prompt, ...} return. Idle with a
    # phase marker is the correct pause primitive.
    {:noreply, new_state}
  end

  # --- Review decisions from the manager ---

  @impl true
  def handle_event({:review, :approve}, %State{phase: :awaiting_review} = state) do
    cond do
      state.current_step >= state.total_steps ->
        {:halt, %{state | phase: :done}}

      true ->
        next_step = state.current_step + 1
        prompt = next_step_prompt(state.task, state.draft, next_step, state.total_steps)
        {:prompt, prompt, %{state | current_step: next_step, phase: :drafting}}
    end
  end

  def handle_event({:review, {:revise, feedback}}, %State{phase: :awaiting_review} = state)
      when is_binary(feedback) do
    prompt = """
    Revise the current draft based on this feedback: #{feedback}

    Current draft:
    #{state.draft}
    """

    {:prompt, prompt, %{state | feedback: feedback, phase: :drafting}}
  end

  def handle_event({:review, :finish}, %State{phase: :awaiting_review} = state) do
    {:halt, %{state | phase: :done}}
  end

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

  # --- Prompts ---

  defp next_step_prompt(task, previous_draft, next_step, total) do
    """
    You are on step #{next_step} of #{total} for the task: #{task}

    Previous draft:
    #{previous_draft}

    Produce the next refinement. Each step should improve on
    the previous -- tighter, clearer, more specific.
    """
  end
end

Using it

{:ok, _pid} = GenAgent.start_agent(Checkpointer.Agent,
  name: "pitch",
  backend: GenAgent.Backends.Anthropic,
  task: "a single-sentence elevator pitch for a time-tracking app",
  total_steps: 3
)

# Kick off the first step.
{:ok, _ref} = GenAgent.tell("pitch",
  "Write an initial draft for: a single-sentence elevator pitch for a time-tracking app")

# Wait for phase: :awaiting_review and read the draft.
# (Use a small poll loop or a helper in your manager module.)
%{agent_state: %{draft: draft, current_step: step}} = GenAgent.status("pitch")
IO.puts("step #{step}: #{draft}")

# Decide what to do next.
GenAgent.notify("pitch", {:review, :approve})
# ... or
GenAgent.notify("pitch", {:review, {:revise, "make it more specific about the target user"}})
# ... or
GenAgent.notify("pitch", {:review, :finish})

# After approve, the next step dispatches automatically. Loop:
# wait_for_review -> inspect -> decide -> repeat.

GenAgent.stop("pitch")

Variations

• Multi-reviewer sign-off. Instead of a single :approve command, require N distinct reviewers to each send a {:review, :approve, reviewer_id} before advancing. Track approvals in state, advance when the set is full.
• Time-boxed review. If no review decision arrives within a deadline, auto-approve or auto-finish. Use a state timeout or an external watchdog that fires a notify.
• Branching plans. Instead of a linear step counter, store a tree of planned steps and let the reviewer choose which branch to explore next via a more complex notify shape.
• Diff-based review. For patterns where each step produces a file change rather than a prose draft, replace draft with a proposed diff and let the reviewer approve/reject it. Commits happen via post_turn/3 once approved. See Workspace for the workspace plumbing half of that.