How Apache Maka Handles Multi-Agent Coordination: Runtime Host and Agent Graph Architecture

Apache Maka implements multi-agent coordination through a centralized Runtime Host that owns all execution authority, layered with a directed-acyclic Agent Graph that schedules child sessions and routes coordination messages through the WorkHub protocol.

Apache Maka is an open-source multi-agent runtime that solves the complexity of coordinating multiple AI agents through a novel architecture combining centralized state management with decentralized agent execution. Understanding how Maka handles multi-agent coordination requires examining its unique approach to session ownership, graph-based scheduling, and durable message protocols. The system ensures deterministic ordering and crash recovery by routing all coordination through a single Runtime Host while maintaining agent isolation via the Agent Graph.

The Runtime Host: Central Execution Authority

The Runtime Host serves as the sole component capable of creating and managing Sessions and Turns across the entire system. According to the architecture documentation in ARCHITECTURE.md, this host acts as the single source of truth for all execution state, preventing race conditions that typically plague distributed multi-agent systems.

All system entry points—including Desktop clients, TUI, CLI, bots, and evaluation frameworks—submit work to this central host rather than communicating directly with individual agents. This design guarantees that every state transition passes through one authoritative checkpoint, enabling reliable ordering and recovery for complex multi-agent workflows.

The Agent Graph: DAG-Based Scheduling Layer

Maka structures agent relationships as an Agent Graph, a directed-acyclic graph (DAG) maintained by the Runtime Host. This graph represents dependency relationships between agents, where each agent operates within its own isolated Session.

The graph scheduler creates child Sessions for each participating agent and tracks their activation states. When coordination events occur, the scheduler routes them back through the Runtime Host, ensuring that parent-child relationships and execution order respect the DAG structure. This approach prevents circular dependencies while allowing sophisticated orchestration patterns where agents delegate work to subordinates.

The scheduling logic and coordination layer design are detailed in the draft specification at docs/architecture/agent-graph-stream-scheduling-draft.md.

WorkHub Coordination Protocol

Coordination Sessions and Roles

Multi-agent coordination in Maka relies on specialized WorkHub Coordination Sessions identified by the role workhub_coordination. These sessions provide the concrete messaging protocol that agents use to negotiate work distribution and orchestration.

The protocol implementation resides in packages/runtime-host/src/protocol/workhub-coordination.ts, which defines the message types, operation specifications, and validation logic used throughout the coordination lifecycle.

Coordination Actions and Message Types

Agents communicate through specific coordination message types with the workhub_coordination discriminator. The protocol supports seven distinct actions:

• answer – Finalize a coordination request with a response
• clarify – Request additional information before proceeding
• delegate_existing – Transfer work to an existing agent session
• create_new – Spawn a new agent to handle specific work
• replace – Substitute one agent delegation with another
• stop_work – Terminate an ongoing agent operation
• resume_work – Restart previously stopped work

Each action passes through decoding functions such as decodeWorkHubCoordinationActInput and decodeWorkHubCoordinationActResult defined in the protocol file, ensuring type safety and schema validation across the coordination boundary.

Durable State Persistence

Coordination metadata persists in the SQLite Session Metadata Store located at packages/storage/src/sqlite-session-metadata-store.ts. This store maintains a unique index for each coordination session and records delegation turn IDs, allowing the graph scheduler to resolve ownership of specific work items at any moment.

By persisting state in SQLite rather than memory, Maka enables crash recovery and session replay without losing coordination context or agent delegation history.

Implementing Multi-Agent Coordination

Developers interact with the coordination system through the Runtime Host API. The following examples demonstrate common multi-agent coordination patterns.

Creating a Coordination Session

Initiate a new coordination context to begin multi-agent orchestration:

import { invoke } from '@maka/runtime-host';

await invoke('workhub.coordination.create', {
  // Allocates a new coordination session with workhub_coordination role
});

Querying Available Agents

Before delegating work, query the candidate pool to obtain valid agent references:

const { candidateSetId, candidates } = await invoke(
  'workhub.coordination.candidates',
  {}
);

Delegating to Existing Agents

Transfer work to a specific agent using the delegate_existing disposition:

await invoke('workhub.coordination.act', {
  actionId: 'a1b2c3',
  userText: 'Please handle the file upload',
  proposal: {
    disposition: 'delegate_existing',
    candidateRef: 'candidate-xyz',
  },
  candidateSetId: 'sha256:0123…abcd',
});

Stopping Delegated Work

Terminate ongoing operations safely using the stop_work action:

await invoke('workhub.coordination.act', {
  actionId: 'stop-123',
  userText: 'Cancel the upload',
  proposal: {
    disposition: 'stop_work',
    expects: { targetSessionId: 'session-xyz' },
  },
  confirmation: { kind: 'user_stop' },
});

Resolving Coordination Turns

Finalize the coordination sequence and persist outcomes:

await invoke('workhub.coordination.resolve', {});

Action Gate: Validating Destructive Operations

The WorkHub Coordination Action Gate in packages/runtime-host/src/server/workhub-coordination-action-gate.ts enforces durable state checks before applying destructive coordination actions. This gate authorizes sensitive operations such as stop_work and resume_work by validating them against the current session metadata stored in SQLite.

The Action Gate ensures that only live, active delegations can be stopped or resumed, preventing stale operations from corrupting the Agent Graph state. It acts as a protective barrier between the coordination protocol and the underlying storage layer, rejecting invalid state transitions before they reach the metadata store.

Summary

• Centralized Authority: The Runtime Host owns all session and turn management, providing a single source of truth for multi-agent coordination.
• Graph-Based Scheduling: The Agent Graph uses a DAG structure to manage dependencies between agent sessions, ensuring deterministic execution order.
• Durable Protocol: The WorkHub Coordination Session provides type-safe messaging with persistent state backed by SQLite.
• Validation Layer: The Action Gate prevents invalid state transitions by checking live delegation status before destructive operations.
• Comprehensive Logging: The Runtime Event Log maintains an append-only record of all coordination messages, enabling full recovery and replay capabilities.

Frequently Asked Questions

How does Apache Maka prevent race conditions between coordinating agents?

Maka eliminates race conditions by centralizing all execution authority in a single Runtime Host that owns every Session and Turn. The Agent Graph scheduler routes all coordination messages through this host, ensuring that state updates occur sequentially rather than concurrently. The SQLite-backed Session Metadata Store provides transactional guarantees for delegation state, while the Action Gate validates all operations against live session data before application.

What happens when an agent needs to stop work delegated to another agent?

When stopping delegated work, the coordinating agent sends a stop_work action through the workhub.coordination.act endpoint. The Action Gate in workhub-coordination-action-gate.ts validates that the target session is still active by checking the SQLite Session Metadata Store. Only valid live delegations receive the stop command, preventing errors from stale session references. The Runtime Host then updates the Agent Graph to reflect the stopped state and records the termination in the Runtime Event Log.

How is coordination state recovered after a system crash?

Maka achieves crash recovery through the SQLite Session Metadata Store and the append-only Runtime Event Log. The metadata store persists coordination turn IDs and delegation relationships durably, while the event log records every message, tool call, and result. Upon restart, the Runtime Host replays these logs to reconstruct the Agent Graph and restore all active coordination sessions to their pre-crash states, ensuring no work is lost between agents.

Where is the graph scheduling logic defined in the source code?

The graph scheduling architecture is documented in docs/architecture/agent-graph-stream-scheduling-draft.md, while the concrete coordination protocol implementation resides in packages/runtime-host/src/protocol/workhub-coordination.ts. The actual execution and session management logic is embedded within the Runtime Host core, which coordinates child sessions according to the DAG structure defined in the Agent Graph specification.

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