Understanding the Two Scheduling Mechanisms in Mako for Multi-Agent Workflows

Mako provides two distinct scheduling mechanisms for multi-agent workflows: the Explicit Workflow-Graph (Copy-on-Write) Scheduler for deterministic DAG-based execution, and the Mailbox (Message-Driven) Scheduler for dynamic, conversational orchestration.

Mako, the Apache open-source framework for building multi-agent systems, implements dual scheduling strategies that allow developers to choose between strict, deterministic execution and flexible, message-driven coordination. These scheduling mechanisms in Mako for multi-agent workflows determine how subagents are spawned, how tasks are delegated, and how control flow progresses across agent interactions. According to the architectural documentation, developers can select the model that best fits their use case—whether building batch processing pipelines or interactive agent swarms.

The Two Scheduling Mechanisms in Mako

The Mako runtime supports two fundamentally different approaches to coordinating multiple agents. Each mechanism offers distinct trade-offs between determinism, isolation, and conversational flexibility.

1. Explicit Workflow-Graph (Copy-on-Write) Scheduler

The Explicit Workflow-Graph Scheduler treats subagents as workflow operators within a directed acyclic graph (DAG). In this model, the main agent constructs a graph that defines explicit dependencies between tasks, and the scheduler advances nodes only when all inbound dependencies are satisfied.

This architecture follows a copy-on-write (CoW) semantics: when spawning a subagent, the parent provides a self-contained task specification rather than the full conversation history. This ensures strict isolation between agents while maintaining deterministic execution order. The approach is ideal for batch-style pipelines where reproducibility and clear dependency chains are critical.

Key characteristics:

• Deterministic DAG-based execution
• Strict isolation through self-contained task specs
• Explicit dependency management between subtasks

2. Mailbox (Message-Driven) Scheduler

The Mailbox Scheduler enables a more dynamic coordination pattern where subagents act as collaborative participants with private, addressable identities. Rather than following a pre-defined graph, agents communicate through asynchronous message passing via dedicated mailboxes.

Control flow emerges organically from the conversation itself, allowing agents to exchange information over multiple turns. This message-driven scheduling supports conversational patterns and event-driven architectures where the sequence of interactions cannot be fully predetermined.

Key characteristics:

• Asynchronous message passing between addressable agents
• Emergent control flow from conversation patterns
• Multi-turn dialogue support across agent boundaries

Implementation Details and Source Code

The Mako codebase implements these dual scheduling strategies through distinct subsystems located in specific packages.

Workflow-Graph Scheduler Components

The deterministic scheduler relies on a core task abstraction and a coordinating engine. In packages/core/src/scheduled-task.ts, Mako defines the data model that represents scheduled units of work, including catalog references, scheduling metadata, and execution status.

The concrete scheduling logic resides in packages/runtime-host/src/server/scheduled-task-coordinator.ts. This coordinator implements the engine that walks the DAG and advances tasks based on dependency readiness. When the main agent spawns isolated subagents, the operation is handled through packages/core/src/subagent-workspace.ts, which demonstrates how the copy-on-write model creates self-contained execution contexts.

Mailbox Scheduler Components

For the message-driven path, Mako implements mailbox communication utilities that handle addressable inboxes and asynchronous delivery. The packages/runtime/src/mailbox.ts module provides the infrastructure for the Mailbox Scheduler, enabling agents to maintain private identities and receive messages independently of the DAG structure.

Practical Usage Examples

Using the Workflow-Graph Scheduler

To leverage the copy-on-write DAG scheduler, developers use the agent_spawn API to create isolated subagents with explicit task specifications:

// Main agent creates a subagent with a self-contained task spec
await agent_spawn({
  subagent_id: "local-reader",
  task: `
    Inspect how the storage package handles concurrent writes,
    citing files and symbols.
  `
});

In this pattern, the runtime spawns an isolated sub-session that receives only the explicit task payload. The scheduler records this node in the workflow graph and invokes the subagent once its prerequisites are satisfied. This approach prevents conversation history leakage and ensures that each subagent operates on exactly the context provided.

Using the Mailbox Scheduler

For conversational multi-agent workflows, Mako provides mailbox-based communication:

// Each subagent has a unique mailbox address
await mailbox.send({
  to: "agent-42",
  message: {
    type: "request",
    payload: { action: "search", query: "latest security patches" }
  }
});

// Later, the same mailbox receives the response
const reply = await mailbox.receive("agent-42");

Here, agents communicate by posting messages to one another's mailboxes. The mailbox scheduler delivers messages asynchronously, enabling the global control flow to evolve across multiple conversational turns without requiring a pre-defined DAG structure.

Summary

• Mako implements two scheduling mechanisms for multi-agent workflows: the Explicit Workflow-Graph (Copy-on-Write) Scheduler and the Mailbox (Message-Driven) Scheduler.
• The Workflow-Graph Scheduler in packages/runtime-host/src/server/scheduled-task-coordinator.ts provides deterministic, DAG-based execution with strict isolation through self-contained task specifications.
• The Mailbox Scheduler enables dynamic, message-driven coordination where agents communicate asynchronously via addressable mailboxes.
• Developers choose between deterministic batch processing (workflow-graph) and flexible conversational patterns (mailbox) based on application requirements.
• Source file packages/core/src/scheduled-task.ts defines the data model used by the graph scheduler, while packages/core/src/subagent-workspace.ts handles copy-on-write subagent creation.

Frequently Asked Questions

What is the primary difference between the Workflow-Graph and Mailbox schedulers in Mako?

The Workflow-Graph Scheduler uses a deterministic directed acyclic graph where subagents execute as isolated nodes with self-contained task specifications, ideal for batch processing with strict dependencies. The Mailbox Scheduler uses asynchronous message passing between addressable agents, allowing dynamic, conversational workflows where control flow emerges from the interaction pattern rather than a pre-defined structure.

How does the copy-on-write mechanism work in Mako's Workflow-Graph Scheduler?

When spawning subagents via agent_spawn() as implemented in packages/core/src/subagent-workspace.ts, the parent agent provides only an explicit task payload rather than the full conversation history. This copy-on-write approach ensures that child subagents operate in isolated contexts with strictly defined inputs, preventing side effects from shared state while the scheduled-task-coordinator.ts engine manages execution order based on DAG dependencies.

When should I use the Mailbox Scheduler instead of the Workflow-Graph Scheduler?

Choose the Mailbox Scheduler when building conversational agents or event-driven systems where the sequence of interactions cannot be fully predetermined and agents need to exchange multiple messages over time. Use the Workflow-Graph Scheduler for batch-style pipelines requiring deterministic execution, strict reproducibility, and clear dependency chains between computational tasks.

Where can I find the architectural documentation describing these two scheduling approaches?

The high-level architectural description of both mechanisms is located in docs/blogs/multi-agent-scheduling.md within the Apache Maka repository (specifically lines 28-31). This document introduces the copy-on-write and mailbox patterns as the two fundamental paths for multi-agent scheduling in the Mako framework.

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