Back
49/65
Lesson 49
10 min
Agent Swarm Coordination
Orchestrate multi-agent swarms with NTM, WA, Agent Mail, and BV
Ready to level up?
Mark complete to track your learning progress.
Orchestrate multi-agent swarms with NTM, WA, Agent Mail, and BV
Mark complete to track your learning progress.
Run a complete multi-agent task loop with Beads robot triage, Agent Mail reservations, RCH-backed builds, UBS scanning, and a clean handoff.
Running a single AI agent is simple. Running 3-6 agents simultaneously across multiple providers requires coordination. The flywheel provides a complete pipeline:
bv --robot-next and br ready --jsonrch exec -- for heavy Rust gates and scan with UBSRobot triage selects work, then CASS and CM recover bounded prior context
Start with machine-readable task state, then pull only the prior context that can change the plan. Memory is a preflight hint; current repo files and Beads state remain the source of truth.
# Pick ready work without launching an interactive TUIbv --robot-nextbv --robot-triagebr ready --json# Inspect and claim exactly one Beadbr show bd-1234 --jsonbr update bd-1234 --status in_progress# Pull bounded memory and session historycm context "bd-1234 checkout validation in /data/projects/my-app" \--workspace /data/projects/my-app --limit 5 --history 3 --jsoncass search "checkout validation command shape" \--workspace /data/projects/my-app --limit 5 --fields summary --json --max-tokens 1200# Register Agent Mail identity through MCP toolsensure_project(human_key="/data/projects/my-app")register_agent(project_key="/data/projects/my-app",program="codex-cli",model="gpt-5",task_description="bd-1234 checkout validation")
A swarm stays calm when each agent owns a tight surface. Reserve only the files you expect to touch, then announce the claim in the Bead thread.
# Optional: split a larger queue by coherent labelsbv --robot-triage-by-label# Reserve via Agent Mail MCP before editingfile_reservation_paths(project_key="/data/projects/my-app",agent_name="BlueLake",paths=["src/checkout/session.ts", "tests/checkout/session.test.ts"],ttl_seconds=3600,exclusive=true,reason="bd-1234: checkout validation")# Announce the start in-threadsend_message(project_key="/data/projects/my-app",sender_name="BlueLake",to=["GreenCastle"],thread_id="bd-1234",subject="[bd-1234] Start: checkout validation",body_md="Reserved checkout session files. Plan: validation plus focused tests.")
Keep implementation narrow, then run the smallest meaningful gate first. Rust-heavy gates should go through RCH so parallel agents do not overwhelm the local host.
# Rust checks use remote compilationrch exec -- cargo testrch exec -- cargo clippy# Web checks use Buncd apps/webbun run type-checkbun run lintbun run build# Scan only the changed files before commitubs src/checkout/session.ts tests/checkout/session.test.ts
Agent Mail provides structured messaging between agents. When one agent completes a dependency, it posts in the same Bead thread so dependents know what changed.
send_message(project_key="/data/projects/my-app",sender_name="BlueLake",to=["GreenCastle"],thread_id="bd-1234",subject="[bd-1234] API endpoints ready",body_md="GET /users and POST /users are implemented and covered by tests.")fetch_inbox(project_key="/data/projects/my-app",agent_name="GreenCastle",include_bodies=true)
A swarm task is not done when the patch works locally. Close the Bead, sync the issue export, commit the exact changed files, release reservations, and leave a final handoff in the thread.
br close bd-1234 --reason "Implemented checkout validation"br sync --flush-onlygit statusgit add src/checkout/session.ts tests/checkout/session.test.ts .beads/git commit -m "fix(checkout): validate checkout sessions"git push origin maingit push origin main:masterrelease_file_reservations(project_key="/data/projects/my-app",agent_name="BlueLake")send_message(project_key="/data/projects/my-app",sender_name="BlueLake",to=["GreenCastle"],thread_id="bd-1234",subject="[bd-1234] Completed: checkout validation",body_md="Landed commit abc123. Gates: type-check, lint, build, UBS. Reservations released.")
Finished work is closed and exported with br sync --flush-only
Only owned files and Beads export changes are staged
Other agents can safely pick nearby work
The final note lists changes, gates, and residual risk