Multi-agent orchestration: several agents, one goal, a real run

Who orchestrates

Frameworks make you write the orchestrator in code. With Swarm, the orchestrator is the AI you are already talking to. It reads the goal, decides the parts, and calls Swarm's tools to run them. Swarm does the rest: every agent runs on your machine, on its own branch, with its own record of what it did and cost.

The goal we gave it

Two tasks started in the same second:

// finder: reads and reports, changes nothing
{ "role": "finder", "title": "How CLIs name CSV output",
  "brief": "How do common command-line tools name an option that prints CSV (for example cloc, psql, sqlite3, kubectl, gh)? Recommend one name for tally.sh and say why in three sentences. Change nothing." }

// coder: works on its own branch
{ "role": "coder", "title": "CSV output",
  "brief": "Add a --csv flag to tally.sh that prints the same rows as comma-separated values with a header line file,lines,words,chars. Document it in README.md with an example. Add checks to test.sh." }

What came back

The finder and the coder agreed on the name independently, which is the check you want from parallel research: if they had not, your AI would have sent the coder a correction before merging.

When branches collide

Parallel agents can touch the same lines. In our run another coder had already changed how the total line prints, and that change was merged first. When we asked Swarm to merge the CSV branch, it refused before touching the folder and named the file:

Swarm rejected the request (HTTP 400): prepare integration failed: ...
CONFLICT (content): Merge conflict in tally.sh

Your folder stays as it was. The fix is to send the coder a message in the same session ("main moved; rebase onto it and keep both behaviors") with swarm_send_message; it updates its own branch, and the review runs again before anything is merged. Keeping parallel tasks on separate files avoids most of this.

Rules that keep orchestration sane

• Split by files, not by steps. Parts that edit different files merge cleanly; parts that wait on each other gain nothing from running in parallel.
• Research changes nothing. A finder only reads and reports, so it can always run alongside the coders.
• Review before merge. One workflow puts every coder task in the folder through a reviewer, with a cap on send-back rounds.
• Watch the bill. Every task reports tokens and cost; swarm_set_limits caps concurrent jobs and daily spend.