Swarm Agents

Swarm mode deploys persistent, autonomous agents orchestrated by a Lead Agent through an event-driven decision loop with a file_read inner loop. The Lead decomposes the user query into tasks, spawns role-specialized agents, monitors their progress through events (idle, completed, checkpoint), reads workspace files to verify quality (zero LLM cost), and coordinates multi-phase execution until all work is done. A closing checkpoint decides whether the Lead can reply directly or trigger LLM synthesis. Agents run reason-act loops for up to 50 iterations, using tools, sharing findings through a workspace filesystem, and going idle (not done) when their current task is complete — with a mandatory QUALITY SELF-CHECK and key_findings before idle. The Lead controls agent lifecycle and can reassign idle agents to new tasks. Agents can escalate issues to the Lead via send_message to "lead".

` ┌──────────────────────────────────────────────────────────────────────┐ │ SwarmWorkflow │ │ Phase 1: Lead initial_plan → Phase 2: event loop → Phase 3: close │ └──────────┬──────────────────────┬────────────────────┬───────────────┘ │ │ │ ┌─────▼──────┐ ┌─────▼──────┐ ┌──────▼──────┐ │ AgentLoop │ │ AgentLoop │ │ Lead Agent │ │ (Takao) │ │ (Mitaka) │ │ /lead/decide│ │ role: │ │ role: │ │ event-driven│ │ researcher │ │ analyst │ │ loop │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ idle / completed │ agent_idle / │ │ ─────────────────► │ agent_completed │ │ │ ────────────────►│ │ │ │ ┌─────▼──────────────────────▼─────┐ │ │ Session Workspace (Files) │◄──── reads ───┘ │ file_write / file_read / etc. │ └───────────────────────────────────┘ ` Key components: | Component | File | Purpose | |-----------|------|---------| | SwarmWorkflow | go/.../workflows/swarm_workflow.go | Top-level Temporal workflow (Lead loop + agent coordination) | | AgentLoop | Same file (child workflow) | Per-agent reason-act loop | | LeadDecision | go/.../activities/lead.go | Activity calling /lead/decide + file_read inner loop | | Lead protocol | python/.../roles/swarm/lead_protocol.py | Lead system prompt, event types, 12 actions | | Agent protocol | python/.../roles/swarm/agent_protocol.py | Agent system prompt, 4 actions + QUALITY SELF-CHECK | | Role prompts | python/.../roles/swarm/role_prompts.py | 12 role-specific methodology prompts | | Lead endpoint | python/.../api/lead.py | /lead/decide HTTP endpoint | | P2P + TaskList | go/.../activities/p2p.go | Mailbox, workspace, task CRUD (Redis) | | Config | config/features.yaml + go/.../activities/config.go | Swarm parameters and defaults | | Synthesis template | config/templates/synthesis/swarm_default.tmpl | Final output formatting | | Agent names | go/.../agents/names.go | Deterministic station-name generation | | Stream events | go/.../activities/stream_events.go | SSE event emission |

SwarmWorkflow receives a TaskInput with "force_swarm": true in context. Instead of a static decomposition, the Lead Agent makes the first decision: • Lead receives an initial_plan event containing the user query • Lead decomposes the query into tasks (with IDs like T1, T2, T3) • Lead decides which agents to spawn, assigning each a role and task • Lead can set depends_on relationships between tasks The Lead's actions from initial planning are executed: tasks stored in Redis, agents spawned as child workflows with role-specific prompts.

Each agent runs an AgentLoop (child workflow) with up to max_iterations_per_agent (default: 50) reason-act cycles. Agent iteration loop: ` ┌──────────────────────────────────────────────────────────────┐ │ 1. Non-blocking shutdown check (signal from Lead) │ │ 2. Inject context: Task Board + Running Notes + Role prompt │ │ 3. Call LLM (/agent/loop) with history + workspace state │ │ 4. Execute action: │ │ • tool_call → run tool, record result │ │ • publish_data → share findings with team workspace │ │ • send_message → P2P to specific agent │ │ • idle → signal parent, wait for reassignment │ │ 5. If agent says "done" and TeamRoster exists → convert to │ │ "idle" (Lead controls lifecycle) │ │ 6. Check convergence / error thresholds │ │ 7. Loop or exit │ └──────────────────────────────────────────────────────────────┘ ` Lead event-driven loop (runs concurrently): The Lead monitors agents through Temporal signals and timers: | Event Type | Trigger | Lead Response | |-----------|---------|---------------| | agent_idle | Agent finished task, waiting | Assign new task, spawn helper, or shutdown | | agent_completed | Agent child workflow done | Quality gate (ACCEPT/RETRY), update task status | | checkpoint | Every 2 minutes | Review progress, revise plan if needed | | human_input | User sends HITL message | Incorporate feedback, adjust plan | For each event, the Lead calls /lead/decide with: current TaskList, agent states, budget, decision history, and any agent→Lead messages. The Lead returns actions that the workflow executes. If the Lead returns file_read actions, the workflow reads the requested files and calls /lead/decide again with file contents injected — this file_read inner loop runs up to 3 rounds per event at zero LLM cost. The Lead can also return interim_reply to send user-visible progress messages without interrupting the workflow.