A session process that owns N GenAgent sub-agents under a strategy.
Where GenAgent gives you one process per LLM session, GenAgentEnsemble
gives you one process per logical session -- the single-agent case
is GenAgentEnsemble.Strategies.Solo, multi-agent patterns like
Supervisor or Pool are other strategies.
Public API
{:ok, pid} = GenAgentEnsemble.start_link(
name: "research-1",
strategy: GenAgentEnsemble.Strategies.Solo,
opts: [agent: {"worker-a", MyAgent, backend: GenAgent.Backends.Mock}]
)
{:ok, token} = GenAgentEnsemble.tell("research-1", "hello")
{:ok, :pending} = GenAgentEnsemble.poll("research-1", token)
# ...later...
{:ok, :completed, response} = GenAgentEnsemble.poll("research-1", token)
{:ok, response} = GenAgentEnsemble.ask("research-1", "quick question", timeout: 30_000)See GenAgentEnsemble.Strategy for how to implement your own strategy.
Summary
Functions
Synchronous prompt. Blocks until the strategy replies or the default timeout expires.
Like ask/2 with options. Supports timeout: plus any
strategy-specific keys (e.g. agent: for Switchboard).
Drain every completed tell token since the last call. Returns
{:ok, [{token, {:ok, response} | {:error, reason}}, ...]}.
List the names of all running ensembles, sorted.
Send an asynchronous event to the strategy (handle_notify/2).
Non-blocking check on a tell-minted token. Returns
{:ok, :pending}, {:ok, :completed, response}, or
{:error, reason}.
Start a new ensemble process. Takes :name, :strategy, and
:opts (the strategy's own options keyword list).
Inspect the ensemble: running agents, strategy phase, queue depth.
Stop the ensemble and its owned sub-agents and prompt tasks.
Like tell/2 but with strategy-specific options (e.g.
agent: "alice" for Switchboard).
Functions
Synchronous prompt. Blocks until the strategy replies or the default timeout expires.
Like ask/2 with options. Supports timeout: plus any
strategy-specific keys (e.g. agent: for Switchboard).
Drain every completed tell token since the last call. Returns
{:ok, [{token, {:ok, response} | {:error, reason}}, ...]}.
@spec list() :: [String.t()]
List the names of all running ensembles, sorted.
iex> GenAgentEnsemble.list()
["qa-pool", "solo"]Send an asynchronous event to the strategy (handle_notify/2).
Non-blocking check on a tell-minted token. Returns
{:ok, :pending}, {:ok, :completed, response}, or
{:error, reason}.
Start a new ensemble process. Takes :name, :strategy, and
:opts (the strategy's own options keyword list).
Inspect the ensemble: running agents, strategy phase, queue depth.
Stop the ensemble and its owned sub-agents and prompt tasks.
Fire-and-forget prompt. Returns {:ok, token} immediately; use
poll/2 or inbox/1 to retrieve the response later.
Like tell/2 but with strategy-specific options (e.g.
agent: "alice" for Switchboard).