Agent Swarmdocs
GitHub

05 -Concepts

Rounds & resolution

A swarm runs 1-3 rounds. In each round every selected agent responds in parallel. Between rounds the swarm resolves - building a directive that carries the prior round's findings forward. The --resolve flag controls how that directive is produced.

Each run: round 1 → resolve → round 2 → … → synthesis

What is a round?

A round is one full parallel sweep of the selected agents. All agents receive the same brief and respond at the same time - a four-agent panel takes about as long as one agent, not four. Each agent returns structured JSON validated against the agent output schema: stance, recommendation, reasoning, risks, open questions, and a confidence level.

The first positional argument to agent-swarm run is the number of rounds. It must be an integer from 1 to 3: 

agent-swarm run 2 "Should we ship the freemium tier this quarter?" \
  --preset product-decision

After the final round the swarm computes a deterministic synthesis - no model call - and writes synthesis.md to the run directory.

Note

Agents run with up to three in parallel at once (the default concurrency). If you select five agents, rounds 1 and 2 of the concurrency window overlap; the total wall-clock time is still much shorter than running agents sequentially.

What happens between rounds?

After each completed round (except the last), the swarm runs a between-rounds pass. This pass produces a directive - a brief that tells agents in the next round what the prior round found and what to focus on. The directive is broadcast as a message to every agent selected for the next round; it appears in that round's brief.md.

How the directive is produced depends on the --resolve mode. The between-rounds pass also checkpoints progress so a failed run can be inspected, and (in orchestrator mode) records question resolutions and deferred questions for the synthesis.

The three resolve modes

Pass --resolve <mode> to agent-swarm run, or set resolve: in a preset or project config. The three canonical values are off, orchestrator, and agents. CLI flags override preset defaults, which override project config values.

Mode Between-round behavior Extra model call? Best for
off Deterministic only - the directive is a templated summary built from the prior round's packet. Question resolutions stay empty. No Fast, cost-free iteration; single-round runs; CI pipelines where predictability matters more than adaptive steering.
orchestrator Real LLM pass - the bundled orchestrator agent reads the prior round's packet and returns a structured directive, question resolutions, deferred questions, and a confidence level. The directive feeds the next round's brief. Yes - one call per between-rounds pass Multi-round runs where you want the swarm to actively steer the next round based on what the previous round surfaced; deeper product or architecture decisions.
agents Reserved - accepted and persisted in manifest.json and synthesis.json, but currently behaves like off. The flag is kept on the CLI surface so agent-driven resolution can land in a future release without renaming it. No (currently) Not yet active. Use orchestrator if you want an adaptive between-round pass today.

off - deterministic, no extra call

The default when --resolve is not set. The between-rounds pass calls buildOrchestratorPassDirective, which assembles a templated summary of the prior packet (stances, recommendations, shared risks, open questions) and broadcasts it as the next round's directive. No model is invoked; the cost is zero; the output is fully reproducible.

Use off when:

  • You are running a single round - there is no between-rounds pass.
  • Speed or cost matters more than adaptive steering.
  • You want the synthesis to be the only place where outputs are aggregated.

orchestrator - LLM-driven directive

The bundled orchestrator agent reads the completed round's packet - including all agent stances, recommendations, risks, and open questions - and returns a structured OrchestratorOutput: a directive for the next round, question resolutions, deferred questions, and a confidence level. The directive replaces the deterministic template in the next round's brief.md.

In orchestrator mode each between-rounds pass also produces:

  • An orchestrator:pass event in events.jsonl with agentName, directive, confidence, questionResolutionsCount, questionResolutionLimit, and deferredQuestionsCount.
  • An entry in the orchestratorPasses array in checkpoint.json - the full OrchestratorOutput snapshot, used if the run is resumed.

If the orchestrator dispatch fails - timeout, malformed JSON after one repair attempt, or non-zero exit - the run finalizes as failed, emits a run:failed event, and exits 1. Successful passes already written to the checkpoint are preserved.

When all selected agents resolve to the same harness and no run-level --backend override is set, the orchestrator agent inherits that harness automatically. Mixed-harness swarms keep the orchestrator on its default.

Use orchestrator when:

  • You are running 2 or 3 rounds and want the swarm to focus the second round on what the first round left unresolved.
  • You want question resolutions and deferred questions captured in the synthesis.
  • The decision is complex enough that templated steering isn't sufficient.

agents - reserved

Accepted by the CLI and persisted in run metadata, but currently behaves identically to off. The flag is reserved so that when agent-driven resolution ships in a future release, no rename is needed. Do not rely on agents producing different output from off today.

Resolve mode synonyms

The CLI accepts shorthand synonyms for each mode so you can use what feels natural on the command line:

Canonical mode Accepted synonyms
off off, none, no, false, 0
orchestrator orchestrator, on, yes, true, 1
agents agents, agent

An unrecognized value throws a SwarmCommandError and exits 2.

A two-round run with orchestrator resolution

This example runs the product-decision preset for two rounds. After round 1 the bundled orchestrator reads the agents' output and produces a targeted directive for round 2. The final synthesis aggregates both rounds deterministically. 

# Two-round run with orchestrator-driven resolution
agent-swarm run 2 "Should we adopt server components?" \
  --preset product-decision \
  --resolve orchestrator \
  --goal "Decide on migration strategy" \
  --decision "Adopt / Defer / Reject" \
  --timeout-ms 300000

The product-decision preset pairs a product-manager and a principal-engineer. In round 1 both respond in parallel to the seed brief. Between rounds the orchestrator reads their stances, risks, and open questions, then writes a directive that steers round 2 toward the disagreements and unresolved questions. Round 2 agents see that directive in their brief before responding. The synthesis then folds both rounds into one call.

You'll find the run artifacts under .agent-swarm/runs/<timestamp>-<slug>/, including round-01/brief.md, round-02/brief.md (which embeds the orchestrator's directive), events.jsonl with an orchestrator:pass event, and synthesis.md.

Note

Real harnesses can take longer than the default 120 s dispatch timeout. Bump --timeout-ms for deeper multi-round runs. The orchestrator pass itself also counts against this timeout.

Where next