GenAgent is a behaviour, not a framework. It gives you a state
machine, a backend abstraction, and lifecycle hooks, and then gets
out of your way. This guide collects the common topologies people
actually build on top of it -- how a human drives a single session,
how agents work autonomously, how multiple agents cooperate, how
failures are recovered, and so on -- as complete worked examples.
Each pattern on this page is a self-contained callback module (plus
a small manager-facing facade in some cases) that you can read,
adapt, and drop into your own application. They are not shipped
as public API modules -- there's no deps.get step and no stable
module names to match against. They're reference implementations.
Copy the parts you need, simplify what you don't, and let the rest
age out.
The patterns are backend-independent. Everything demonstrated here
works against any GenAgent.Backend implementation, and we test
them in the playground against a mix of Claude, Codex, Anthropic
HTTP, and the in-memory Mock backend.
Patterns at a glance
| Pattern | Topology | Key gen_agent features |
|---|---|---|
| Switchboard | Human-managed named fleet | tell/poll, notify, inbox cursor, telemetry |
| Research | Autonomous self-chain (1 agent) | {:prompt, ..., state} state machine, handle_error |
| Debate | Two agents, cross-agent notify | Cross-agent notify, handle_event -> prompt, mutual halt |
| Pipeline | Linear stage chain | One-way notify chain, per-stage self-halt |
| Supervisor | Coordinator + dynamic worker pool | start_agent/2 from inside a callback, fan-out/fan-in |
| Pool | Reusable worker pool, round-robin | Multi-turn workers, tell/2 mailbox queueing |
| Watcher | Reactive event-driven agent | handle_event filtering, idle-until-triggered |
| Checkpointer | Human-in-the-loop review workflow | Idle-with-phase-marker pause primitive |
| Retry | handle_error self-chain retry loop | handle_error returning {:prompt, ..., state} |
| Workspace | Single agent + temp git workspace | All four v0.2 lifecycle hooks |
Choosing a pattern
Most real agents end up being a combination, not a pure instance of one of these. A rough decision tree:
You want a human driving one or more long-lived sessions from iex or an MCP client. Start with Switchboard. It's the thinnest layer on top of
GenAgentand matches the "manager is the interface" model.One agent needs to walk itself through several phases of work without human input. Start with Research. The self-chain via
{:prompt, ..., state}is the whole move.Work has to flow through a fixed sequence of distinct agents, each with its own role. Start with Pipeline.
One coordinator needs to fan work out to N variable workers and collect the results. Start with Supervisor if workers are one-shot, or Pool if they're long-lived and round-robin dispatched.
Two agents with opposing roles need to push each other forward. Use Debate. Cross-agent
notifyis the primitive.An agent should sit idle until events arrive (CI failures, file changes, webhooks). Start with Watcher.
An agent should do something, then pause for human review, then continue based on the review decision. Start with Checkpointer. The key move is idle-with-phase-marker rather than
{:halt, state}-- halt is terminal, idle is resumable.Transient failures need to trigger retries with backoff, and you want the retry decision to live on agent state. Start with Retry.
Every turn needs to run against an isolated git worktree, with per-turn commits and a completion hook. Start with Workspace. This is also the best full example of gen_agent v0.2 lifecycle hooks in action.
What these patterns are NOT
Not a cookbook you install as a dependency. Each page is code you read and copy. If you want a library layer on top of
GenAgent, build it in your own application with whatever opinionation you need.Not exhaustive. The shapes that are here are the ones that came up naturally while dogfooding
GenAgentagainst real backends. If you find yourself building a topology that isn't here, it's not missing on purpose -- it just hasn't been needed yet.Not opinionated about prompts. All example prompts are deliberately short. Real agents have real prompt engineering inside them, and we assume you'll write your own.