GenAgent gives each agent an OTP process, a backend, and lifecycle
callbacks. The patterns in this guide cover two ways to build on it:
shipped strategies in
gen_agent_ensemble,
and callback-level reference implementations you can adapt in your own
application.
An Ensemble session owns its sub-agents under one strategy. Add
{:gen_agent_ensemble, "~> 0.1.4"} to your dependencies and start a
session with GenAgentEnsemble.start_link(name: ..., strategy: ..., opts: ...). Submit with ask for a synchronous result or tell
followed by poll or inbox. An agent spec chooses its callback module
and backend options, so one session can use different backends for
different roles. The separate
gen_agent_server
application adds named instances, bounded result retention, CLI access,
and optional scheduling around these strategies.
Shipped Ensemble strategies
| Strategy | Shape | When it fits |
|---|---|---|
GenAgentEnsemble.Strategies.Solo | One agent | A single session behind the Ensemble API. |
GenAgentEnsemble.Strategies.Switchboard | Caller-routed named agents | A human or client chooses agent: on each call. |
GenAgentEnsemble.Strategies.Pipeline | Ordered stages | Each stage's response text becomes the next prompt. |
GenAgentEnsemble.Strategies.Supervisor | Coordinator and temporary workers | Decompose one request, run independent sub-tasks, collect replies. |
GenAgentEnsemble.Strategies.Pool | Fixed reusable workers | Dispatch to the next free worker; queue requests FIFO when all are busy. |
GenAgentEnsemble.Strategies.Debate | Two alternating agents | Continue until a convergence rule or round cap ends the exchange. |
GenAgentEnsemble.Strategies.Consensus | N agents with parsed verdicts | Compare decisions against a threshold and report divergence at the round cap. |
The Switchboard, Pipeline, Supervisor, Pool, and Debate pages predate the packaged strategies. Their callback modules are alternative examples, not the implementations behind those strategies. Use each strategy's module documentation for its exact options and failure semantics. These guide pages include a short example of starting the packaged strategy before the older callback recipe.
Single-agent callback patterns
These pages show shapes within one agent process. Read and adapt the callback module rather than expecting an installable strategy:
When adapting a callback example, make the options returned by
init_agent/1 match the selected backend. Examples that return :system
or :max_tokens need different options for the Codex backend; see its
backend options.
| Pattern | Use |
|---|---|
| Research | Self-chain through phases with {:prompt, ..., state}. |
| Watcher | Wait for an event and decide whether it starts a turn. |
| Heartbeat | React to periodic tick events. |
| Checkpointer | Pause for human input while remaining resumable. |
| Retry | Decide on retry and backoff in agent state. |
| Workspace | Run turns in isolated Git workspaces with lifecycle hooks. |
Choosing a pattern
Use Switchboard when the caller knows which named agent should receive each request. Use Pipeline when roles have a fixed order, and Supervisor when one request can be decomposed into temporary, independent workers. Use Pool for a stream of independent requests that should reuse a bounded set of workers. Debate and Consensus add explicit convergence rules; the latter parses categorical verdicts from two or more agents.
Use a callback pattern for behavior inside one agent: Research for self-directed phases, Watcher or Heartbeat for event-driven work, Checkpointer for a human pause, Retry for recovery, and Workspace for per-turn isolation. These shapes can also be used as sub-agents within an Ensemble strategy.
All examples use short prompts so the process and handoff remain clear. Write task-specific instructions and verify claims against their source when using a real backend.