Apache Maka Agent Graph Stream Scheduling System: How Parallel Operators Execute Without Runtime Duplication
Apache Maka's Agent Graph stream scheduling system is a SQLite-backed control plane that coordinates parallel operator execution through immutable RuntimeEvent projections, deterministic intent claims, and reference-only records—while keeping the existing Session runtime as the sole execution authority.
Apache Maka introduces a novel approach to parallel AI agent execution with its Agent Graph stream scheduling system for parallel operators. Rather than spawning separate Agent runtimes, the system creates a lightweight coordination layer that manages multiple child Sessions (operators) through a durable SQLite control plane. This architecture allows complex multi-step workflows to run concurrently without sacrificing the atomicity guarantees of Maka's core execution model.
Core Architecture: Control Plane vs. Execution Authority
The Agent Graph deliberately does not duplicate the runtime. Instead, it separates concerns into two layers:
- SQLite Control Plane: Stores topology, schedule revisions, admission claims, and supervisor wake state
- Session-Inline Runtime: Retains exclusive authority via
AgentRunandRuntimeEventlogs
This design means the graph layer only projects immutable RuntimeEvent objects into lightweight AgentGraphRecord references. These records describe what happened, never how it happened.
Key Concepts
| Concept | Purpose | Durable Authority |
|---|---|---|
| Root Session | User-facing conversation where the main Agent supervises | Session store |
| Graph | Scheduling namespace derived from the root Session | SQLite control plane |
| Operator | Stable binding between child Session and work unit | Operator provision table |
| Activation | Single execution of an operator | AgentRun ledger |
| RuntimeEvent | Immutable fact from child Session execution | Runtime Event Log |
| Record | Reference-only projection for routing and readiness | Recomputed projection |
The Seven-Stage Scheduling Flow
1. Supervisor Updates via update_agent_graph
The main Agent appends schedule revisions (add, stop, or finish work) through an append-only, idempotent API. As documented in the architecture draft, revision storage guarantees monotonic history without mutation of prior states.
await update_agent_graph({
add_work: [{ agent_id: "assistant", instruction: "review code", input_ids: [] }],
});
2. Operator Provisioning
When a work_item references a new operator_id, the coordinator executes a single transaction that creates both the child Session and the operator binding. This eliminates race conditions between topology creation and execution readiness.
3. Deterministic Intent Claiming with intent admission
Before any execution, the scheduler:
- Computes a deterministic readiness intent
- Pre-allocates Turn/Run IDs
- Writes a claim row to SQLite
This intent admission mechanism provides exactly-once execution guarantees even under crash-recovery scenarios.
const claim = await runClaimedAgentGraphIntent({
graph_id: "root-123",
intent_id: "readiness-456",
});
if (claim.admissionState === "executing") {
await claim.runPromise;
}
4. Child Session Activation
The child Session executes via the standard Session-inline AgentRun path—no special runtime, no execution divergence. All outputs persist to the authoritative Runtime Event Log.
5. Projection via readCommittedAgentGraphProjection()
The system reads committed RuntimeEvent objects and emits bounded AgentGraphRecord projections. These records contain only stable identifiers:
interface AgentGraphRecord {
operator_id: string;
activation_id: string;
runtime_event_id: string;
// No message payloads, no tool outputs
}
6. Routing and Readiness Policies
From AgentGraphRecord objects, the graph computes:
- Routes: Visibility across operator edges
- Readiness intents: Deterministic candidates for new work
Policies like map and all_settled resolve readiness without model invocation, enabling purely mechanical scheduling decisions.
7. Reconciliation Loop
The driver loop in packages/runtime/src/stream-graph-schedule-reconcile.ts repeatedly:
- Reads schedule revisions
- Reconstructs topology
- Resolves pending work
- Claims eligible intents
- Dispatches parallel activations
- Folds new
RuntimeEventobjects into the projection - Halts at quiescence (no eligible intents remain)
Parallelism Without Bottlenecks
Operator Independence
Each operator binds to a dedicated child Session, enabling concurrent activations bounded only by host resource permits. Child Sessions preserve intra-operator ordering (their own activation stream) while proceeding asynchronously across operators.
Dispatch Loop Architecture
The stream-graph-dispatch.ts module launches eligible activations in parallel, respecting external constraints like model rate limits without internal serialization.
Main Agent: Beside, Not Behind
The root Agent stays beside the graph—never becoming a data-path bottleneck. Its three responsibilities are:
- Observe: Query durable state via
view_agent_graph - Control: Modify schedules via
update_agent_graph - Synthesize: Fetch authoritative outputs via
agent_output
// Query current graph state
const view = await view_agent_graph({ graph_id: "root-123" });
// Retrieve final output from completed child work
const output = await agent_output({
childSessionId: "session-789",
runId: "run-012",
view: "result",
});
Because the graph stores only references, the main Agent can inspect or modify schedules while child Sessions process work independently.
Implementation Files in Apache Maka
Summary
- Agent Graph stream scheduling in Apache Maka enables parallel operator execution without duplicating the runtime
- SQLite control plane stores topology and schedule revisions; RuntimeEvent Log remains sole execution authority
- Deterministic intent claiming with
intent admissionguarantees exactly-once execution - Reference-only projections (
AgentGraphRecord) enable routing and readiness without copying message payloads - Child Session parallelism allows concurrent activations while preserving per-operator ordering
- Main Agent supervises beside the graph, controlling schedules without blocking on execution
Frequently Asked Questions
How does Apache Maka's Agent Graph avoid the "double runtime" problem?
The graph layer stores only references (operator IDs, activation IDs, event IDs) in SQLite, never copying actual message payloads or tool outputs. Execution stays entirely within the existing Session-inline AgentRun path. This design preserves Maka's single authoritative Runtime model while adding coordination capabilities.
What guarantees does the intent admission system provide?
The intent admission mechanism in stream-graph-admission.ts provides exactly-once execution through deterministic ID pre-allocation and durable claim rows. Even if a coordinator crashes after claiming but before dispatching, the claim record prevents duplicate work—the same deterministic intent yields the same claim ID on recovery.
Can operators share data, and if so, how?
Operators communicate through reference-only routing, not direct data passing. When a RuntimeEvent is projected into an AgentGraphRecord, the graph creates visibility routes to downstream operators. The main Agent can then fetch actual outputs via agent_output when synthesis requires them—keeping the control plane lightweight and the data path explicit.
What happens when no operators have eligible work?
The reconciliation loop reaches quiescence—a stable state where no readiness intents are eligible for claiming. At this point, the graph pauses until either new work arrives via update_agent_graph or an in-flight activation completes and produces new RuntimeEvent objects that trigger downstream readiness.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →