# How Apache Maka Implements Multi-Agent Scheduling and the Agent Graph

> Learn how Apache Maka uses a transactional Agent Graph with SQLite to manage its multi-agent scheduling pipeline, coordinating tasks via schedules, intent claims, and operator provisions.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-04

---

**Apache Maka implements multi-agent scheduling through a transactional SQLite-backed Agent Graph that manages a schedule-intent-execution pipeline, coordinating sub-agent tasks via revision-tracked schedules, intent claims, and operator provisions.**

Apache Maka is an open-source framework for building autonomous AI agents. Its multi-agent scheduling system centers on the **Agent Graph**, a control-plane abstraction that orchestrates parallel sub-agent execution within a single workspace. The implementation relies on a monolithic SQLite database for consistency, ensuring that concurrent workers can claim and execute intents without conflicts.

## The Schedule-Intent-Execution Pipeline

The Agent Graph operates as a directed state machine where work progresses through discrete phases. Each phase maps to specific operations in the storage layer.

### Schedule Creation and Revision Tracking

Every graph maintains an immutable **schedule revision** that lists the intents (sub-agent tasks) to be executed. When the UI or an orchestrator updates the plan, it creates a new revision via `commitAgentGraphScheduleUpdate` in [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts). This function accepts an `AgentGraphScheduleUpdateRequest` containing the graph ID, a monotonic revision number, and the intent definitions.

```typescript
// Commit a new schedule revision from the UI
await storage.commitAgentGraphScheduleUpdate({
  graphId: "graph-123",
  source: "ui-request",
  updateId: crypto.randomUUID(),
  revision: 2,
  schedule: {
    intents: [
      { intentId: "intent-a", agent: "CodeWriter", payload: { file: "src/index.ts" } },
      { intentId: "intent-b", agent: "WebSearcher", payload: { query: "latest weather" } },
    ],
  },
});

```

### Intent Claiming and Admission

Before a worker (runtime host) executes a sub-agent, it must **claim** the corresponding intent. The `claimAgentGraphIntent` function records the claim with the current schedule revision and worker ID, preventing duplicate execution. If two workers attempt to claim the same `intentId` simultaneously, the storage layer raises an `AgentGraphIntentClaimConflictError`.

```typescript
// Worker claims an intent for execution
const claim = await storage.claimAgentGraphIntent({
  graphId: "graph-123",
  intentId: "intent-a",
  scheduleRevision: 2,
  workId: "worker-01",
});

```

After claiming, the runtime calls `beginAgentGraphIntentExecutionAtScheduleRevision` to admit the intent. This transitions the intent state from **pending** to **running** and returns an `AgentGraphIntentAdmissionTransition` record that the coordinator uses to track live execution.

### Operator Provisioning and Result Persistence

When a sub-agent completes, the runtime persists its results via `createAgentGraphOperator`, which stores an `AgentGraphOperatorProvisionRequest`. This record includes the execution status, output data, and any child sessions spawned by the sub-agent. The provision step effectively marks the intent as completed within the graph, allowing downstream dependents to proceed.

```typescript
// Persist the completed sub-agent result
await storage.createAgentGraphOperator({
  graphId: "graph-123",
  workId: "worker-01",
  operatorId: "op-code-writer-1",
  result: { 
    status: "completed", 
    output: "// generated code", 
    childSessions: [] 
  },
});

```

## SQLite-Backed Control Plane

All Agent Graph state resides in a single SQLite database per workspace. This design leverages ACID transactions to guarantee consistency across distributed workers without requiring an external coordination service.

### Schema and Storage Layer

The database schema, defined in [`packages/storage/src/sqlite-session-metadata-schema.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-schema.ts), includes tables for `AgentGraphSchedule`, `AgentGraphIntentClaim`, and `AgentGraphOperatorProvision`. The `AgentGraphStore` class in [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts) provides the concrete implementations of the schedule and intent management functions, wrapping each operation in a transaction to ensure atomicity.

### Conflict Detection and Error Handling

The storage layer defines specific error types for common coordination failures. An `AgentGraphScheduleRevisionConflictError` occurs when a worker attempts to claim an intent using an outdated revision, while `AgentGraphIntentClaimConflictError` signals that another worker has already claimed the intent. The runtime coordinator in [`packages/runtime/src/agent-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-coordinator.ts) catches these errors and translates them into user-facing status messages, allowing the UI to display "Agent Graph scheduling conflict" warnings.

## Runtime Coordination

The **Agent Graph Coordinator** acts as the bridge between the storage layer and the user interface. It resides in [`packages/runtime/src/agent-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-coordinator.ts) and manages three primary responsibilities: propagating UI-driven schedule commits, processing intent claims from workers, and publishing timeline updates.

### Supervision and Wake-Ups

To handle stalled or crashed executions, the coordinator relies on a lightweight wake-up mechanism. The `beginAgentGraphSupervisorWakeAttempt` function, paired with `AgentGraphSupervisorWakeRecord`, periodically scans for intents that have remained in the **running** state beyond a timeout threshold. When detected, the supervisor cancels the zombie intent and reschedules it, ensuring the graph eventually reaches a consistent terminal state.

## Key Source Files

- **[`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts)** – Core implementations of `commitAgentGraphScheduleUpdate`, `claimAgentGraphIntent`, and `beginAgentGraphIntentExecutionAtScheduleRevision`.
- **[`packages/runtime/src/agent-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-coordinator.ts)** – Runtime bridge that handles UI events, worker claims, and supervisor wake-ups.
- **[`packages/storage/src/sqlite-session-metadata-schema.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-schema.ts)** – SQLite table definitions for schedules, intents, and operator provisions.
- **[`packages/ui/src/tool-activity/agent-graph.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/agent-graph.tsx)** – React component that renders the interactive graph panel and timeline.
- **[`packages/storage/src/__tests__/agent-graph-intent-claims.test.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/__tests__/agent-graph-intent-claims.test.ts)** – Unit tests verifying claim logic, conflict handling, and schedule revision checks.

## Summary

- Apache Maka uses a **SQLite-backed Agent Graph** to coordinate multi-agent execution within a single workspace.
- The system implements a **schedule-intent-execution pipeline** where `commitAgentGraphScheduleUpdate` creates work, `claimAgentGraphIntent` reserves it, and `createAgentGraphOperator` records completion.
- **Transactional consistency** is enforced through SQLite, with specific error types like `AgentGraphIntentClaimConflictError` handling race conditions.
- The **Agent Graph Coordinator** manages the lifecycle of intents, provides UI updates, and recovers from stalled executions via supervisor wake-ups.
- Source implementations reside in [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts) and [`packages/runtime/src/agent-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-coordinator.ts).

## Frequently Asked Questions

### What is the Agent Graph in Apache Maka?

The Agent Graph is a control-plane abstraction that represents a directed workflow of sub-agent tasks (intents) within a conversation. It tracks the state of each intent—from pending to completed—using a SQLite database and allows multiple workers to claim and execute tasks in parallel while maintaining consistency through schedule revisions.

### How does Apache Maka prevent duplicate execution of the same intent?

When a worker intends to run a sub-agent, it calls `claimAgentGraphIntent` in the storage layer. This function performs an atomic insert into the `AgentGraphIntentClaim` table. If another worker has already claimed the intent, the database raises an `AgentGraphIntentClaimConflictError`, forcing the second worker to skip execution or retry with a newer schedule revision.

### What happens when a schedule revision conflict occurs?

A worker claiming an intent must specify the current `scheduleRevision`. If the schedule has been updated between the worker reading it and claiming the intent, the storage layer throws an `AgentGraphScheduleRevisionConflictError`. The runtime coordinator catches this and notifies the UI, typically prompting a refresh of the graph state before the worker attempts to claim work again.

### How does the system recover from crashed or hanging sub-agents?

The `beginAgentGraphSupervisorWakeAttempt` function periodically scans for intents in the **running** state that have exceeded their timeout threshold. When found, the supervisor transitions these intents to a **canceled** or **failed** state, allowing the scheduler to either retry them or mark them as explicitly failed, thus preventing the entire graph from indefinitely blocking on a dead worker.