Understanding Swarm Mode in Maka: Asynchronous Agent Orchestration Explained

Swarm mode is an orchestration mode that directs the main Agent to use the durable asynchronous Agent Graph for handling requests split into independent work items, enabling parallel delegation with lightweight host supervision.

Swarm mode in Apache Maka transforms how agents handle complex tasks by leveraging the underlying Agent Graph scheduler for asynchronous execution. Unlike standard operation, this mode enables the main Agent to fan out independent work items as child Sessions, monitor their progress through compact status tools, and resume only at meaningful checkpoints. The implementation reuses existing machinery—specifically the graph scheduler, ledger, and control plane—while adding specific prompting, tooling, and wake policies optimized for parallel orchestration.

How Swarm Mode Works

When activated, Swarm mode modifies four critical aspects of agent behavior without introducing new execution engines. The system leverages existing infrastructure in packages/runtime/src/swarm-mode.ts and related coordination modules to enable durable asynchronous processing.

System Prompt Injection

The AiSdkBackend automatically appends an orchestration-specific prompt to every turn when Swarm mode is active. According to the source in packages/runtime/src/swarm-mode.ts, the renderSwarmModePrompt() function generates instructions that guide the Agent to consider parallel delegation only when it adds tangible value. This prompt appears as an <orchestration_mode> block that frames the Agent's reasoning around graph-based execution.

Guaranteed Tool Set

Swarm mode automatically populates the turn's tool catalog with five essential functions while deliberately omitting others to maintain focus. The guaranteed tools include:

• agent_list – Enumerates available subagents for delegation
• update_agent_graph – Modifies the graph by adding or replacing work items
• yield_agent_graph – Commits current graph state and yields execution
• agent_swarm_status – Retrieves compact status projections
• agent_output – Returns results from completed items

Notably, the implementation excludes view_agent_graph to prevent the Agent from processing raw graph structures, forcing reliance on the compact agent_swarm_status projections instead. This design is documented in docs/agent-swarm.md and enforced in the runtime tool registration.

Durable Authorization Recording

Every Swarm mode activation is durably recorded in the agentSwarmAuthorization field on the AgentRun header. As implemented in packages/runtime/src/runtime-kernel.ts, this field captures the provenance of the mode activation, storing one of three values:

• session_mode – Persistently enabled for the Session
• turn_override – Activated for a single turn only
• none – Standard non-swarm operation

This authorization trail ensures auditability and prevents accidental mode escalation across session boundaries.

Checkpoint-Based Wake Policy

The supervisor wakes only at specific graph checkpoints rather than processing every micro-transition. The isSwarmCheckpointTransition function in packages/runtime/src/stream-graph-coordinator.ts determines wake eligibility based on two criteria:

1. The first transition to settled status
2. Any change in problematic item states (blocked, failed, aborted, or cancelled)

This policy reduces unnecessary context switches while ensuring the Agent responds promptly to failures or completion events.

Enabling Swarm Mode

Users control Swarm mode through the /swarm command parsed by packages/core/src/swarm-command.ts. The parseSwarmCommand() function handles four distinct invocation patterns:

• /swarm on – Sets the Session's orchestration mode to swarm persistently
• /swarm off – Reverts the Session to default sequential mode
• /swarm or /swarm status – Returns the current mode without modification
• /swarm <task> – Executes a single task in swarm mode without changing the persistent Session mode

This command structure allows both persistent mode shifts and ad-hoc parallel execution.

Status Projection and Monitoring

The agent_swarm_status tool, implemented in packages/runtime/src/agent-swarm-status-tool.ts, returns a structured snapshot defined by the AgentSwarmStatusResult interface:

interface AgentSwarmStatusResult {
  kind: 'agent_swarm_status';
  swarmId: string;               // graphId
  status: 'running' | 'needs_attention' | 'settled';
  counts: Record<AgentSwarmItemStatus, number>;
  items: AgentSwarmStatusItem[];
}

The three derived swarm-level status values provide high-level situational awareness:

• running – Active work remains; no supervisor intervention required
• needs_attention – At least one item is blocked, failed, aborted, or cancelled
• settled – All items reached terminal status (excluding transient states like queued or running)

This compact representation allows the Agent to make orchestration decisions without parsing complex graph structures.

Practical Implementation Examples

The following patterns demonstrate common Swarm mode interactions using the Maka SDK:

// Parse a /swarm command
import { parseSwarmCommand } from '@maka/core/swarm-command';
const cmd = parseSwarmCommand('/swarm on'); 
// Returns: { kind: 'set_mode', mode: 'swarm' }

// Render the system prompt for a turn
import { renderSwarmModePrompt } from '@maka/runtime/swarm-mode';
const prompt = renderSwarmModePrompt(); 
// Returns the <orchestration_mode> block for AI context

// Query swarm status inside a turn
await toolCall('agent_swarm_status', {}); 
// Receives AgentSwarmStatusResult with current graph state

A typical workflow proceeds as follows: the user enables Swarm mode with /swarm on, submits a request that splits into independent review tasks, the Agent calls agent_list and update_agent_graph to create three parallel work items, then invokes yield_agent_graph to suspend. When the coordinator detects a checkpoint transition (such as one failure among three tasks), it wakes the Agent, which queries agent_swarm_status, receives needs_attention status with counts showing two completed and one failed, and issues a replacement via update_agent_graph with replacement_mode: 'replace'.

Summary

• Swarm mode repurposes the existing Agent Graph scheduler for durable asynchronous orchestration without adding new execution machinery.
• Activation modifies the system prompt, guarantees five specific tools, records authorization provenance, and implements checkpoint-based waking.
• Users control the mode via /swarm commands parsed in packages/core/src/swarm-command.ts.
• The Agent Graph stores work items as ordinary child Sessions, with status projected through the compact agent_swarm_status tool.
• Supervision resumes only at meaningful checkpoints—first settlement or failure transitions—reducing host overhead while maintaining responsiveness.

Frequently Asked Questions

What triggers a supervisor wake in Swarm mode?

The supervisor wakes only when isSwarmCheckpointTransition in packages/runtime/src/stream-graph-coordinator.ts detects specific graph events: the first transition to settled status, or any change in items entering blocked, failed, aborted, or cancelled states. This checkpoint policy ensures the Agent intervenes promptly for failures while avoiding unnecessary context switches during normal operation.

How does Swarm mode differ from standard Agent execution?

Standard execution typically processes items sequentially or through immediate tool responses, whereas Swarm mode treats the Agent Graph as the primary execution mechanism. The main Agent delegates independent work items as child Sessions, yields control via yield_agent_graph, and resumes only at checkpoints. This enables true parallel processing with durable persistence, while the compact agent_swarm_status tool replaces direct graph inspection.

Can I use Swarm mode for a single task without enabling it for the entire Session?

Yes. The /swarm <task> syntax allows ad-hoc Swarm execution without persisting the mode change. As parsed by packages/core/src/swarm-command.ts, this command executes the specified task in Swarm mode while preserving the Session's original orchestration settings, making it ideal for one-off parallel processing needs.

Why is the view_agent_graph tool unavailable in Swarm mode?

The tool catalog intentionally omits view_agent_graph to enforce focus on the compact agent_swarm_status projections. According to the implementation in docs/agent-swarm.md, this restriction prevents the Agent from processing verbose raw graph structures, reducing token consumption and cognitive load while ensuring decisions are based on summarized status (running, needs_attention, or settled) rather than granular node details.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}