# Agent Graph Architecture for Multi-Agent Task Scheduling in Apache Maka

> Explore Maka's Agent Graph architecture for efficient multi-agent task scheduling. Orchestrate dynamic work across child agents without a second runtime.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-08-27

---

**Maka's Agent Graph is a durable scheduling layer that lets the main Agent orchestrate dependent, dynamically-expanding work across many child agents without creating a second execution runtime.**

The Apache Maka project implements a sophisticated **agent graph architecture for multi-agent task scheduling** that sits beside the existing Session-based Runtime Host. It uses a SQLite control plane to store topology, schedule intent, admission claims, and supervisor wakes while maintaining the Runtime Event Log as the single source of execution truth.

## How the Agent Graph Extends the Runtime Host

Traditional multi-agent systems often duplicate runtime infrastructure or require the main Agent to approve every step. Maka's approach separates **scheduling facts** from **execution facts**.

The **Runtime Host** remains the sole execution authority, processing Session → AgentRun → RuntimeEventLog flows as defined in the core runtime. The **Agent Graph** adds a lightweight control plane that enables durable orchestration without bottlenecks:

- **Topology** managed in [`packages/core/src/agent-graph-topology.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-topology.ts) maps operators to child Sessions
- **Schedule revisions** in [`packages/core/src/agent-graph-schedule.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-schedule.ts) handle add/stop/finish operations
- **Intent claims** in [`packages/core/src/agent-graph-control.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-control.ts) enforce exactly-once admission
- **Supervisor wakes** in [`packages/runtime/src/agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-supervisor-wake.ts) persist root-Agent turn requests

This design allows normal work to proceed without waiting for the main Agent's approval, while still enabling comprehensive oversight through durable SQLite records.

## Core Components and Data Flow

### The Control Plane Primitives

The architecture defines several key abstractions that enable deterministic scheduling:

- **Operator** = a child Session (stable container reusable for many activations)
- **Activation** = an AgentRun (normal Session-inline execution producing immutable `RuntimeEvent`s)
- **Record** = a bounded projection of a committed `RuntimeEvent` (implemented in [`packages/runtime/src/stream-graph-projection.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-projection.ts))
- **Route** = a reference-only edge making records visible to downstream operators
- **Readiness** = a deterministic projection ([`packages/runtime/src/stream-graph-readiness.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-readiness.ts)) deciding when an intent is runnable
- **Claim** = pre-allocates Turn/Run IDs and marks intent as admitted via `runClaimedAgentGraphIntent`

### Data Flow Architecture

The system follows a strict flow from user action to execution:

1. User triggers a graph-mode task through the main Agent
2. Coordinator provisions operators and writes topology rows to SQLite
3. Readiness projection produces runnable intents
4. Coordinator claims intents with unique identifiers
5. Child Sessions execute via `SessionManager.runAgent`
6. Graph projection reads `RuntimeEvent`s and emits records/routes
7. Downstream operators activate when their readiness conditions satisfy
8. Supervisor wake delivers durable requests to resume root-Agent turns at checkpoints

## Execution Lifecycle

The complete lifecycle of a multi-agent task proceeds through eight precise steps that ensure durability and exactly-once semantics.

### 1. Schedule Updates via the Main Agent

When the main Agent initiates work, it calls `update_agent_graph(add_work)` which writes a schedule row to the SQLite control plane. This operation is append-only and revision-ordered for deterministic replay.

### 2. Operator Provisioning

The coordinator reads the schedule and provisions an operator by creating a child Session. This writes a topology row linking the operator to its Session ID. Operator provision is **monotonic** and retry-safe, ensuring child Sessions are never duplicated even during network partitions.

### 3. Intent Claiming

Before execution, the coordinator generates a readiness projection and **claims** the intent via `runClaimedAgentGraphIntent`. This binds the intent to a unique Turn/Run ID pair, preventing duplicate execution on retries. The claim is persisted in [`packages/runtime/src/stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-admission.ts).

### 4. Child Session Execution

With claims established, the coordinator invokes normal child-Session execution. The child AgentRun writes `RuntimeEvent`s to the event log exactly as non-graph Sessions do.

### 5. Graph Projection

The `readCommittedAgentGraphProjection` function (in [`packages/runtime/src/stream-graph-projection.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-projection.ts)) reads committed `RuntimeEvent`s and transforms them into **AgentGraphRecord** objects. Only committed events become graph records, guaranteeing immutable facts.

### 6. Dynamic Expansion

When a record satisfies downstream operator readiness policies (such as `map` or `all_settled` in [`stream-graph-readiness.ts`](https://github.com/apache/maka/blob/main/stream-graph-readiness.ts)), steps 3-5 repeat automatically. This allows the graph to expand dynamically without main Agent intervention.

### 7. Supervisor Wake Delivery

The **supervisor wake** stores a durable request to start a root-Agent turn. When the graph reaches a useful checkpoint—defined as completion of a determinate set of records—the wake delivers to the main Agent.

### 8. Root Agent Continuation

The main Agent reads the current graph state via `view_agent_graph`, fetches authoritative child output through `agent_output`, and may add more work or call `finish` to complete the schedule.

## Safety Invariants and Guarantees

The architecture enforces six critical invariants that enable crash-safe multi-agent orchestration:

- **Append-only schedule** — All schedule updates are revision-ordered and idempotent, guaranteeing deterministic replay across restarts.
- **Monotonic operator provision** — Child Session creation is retry-safe; duplicate provision attempts are detected and deduplicated via [`packages/core/src/agent-graph-topology.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-topology.ts).
- **Exactly-once claim binding** — Each intent maps to a unique Turn/Run ID through the claim mechanism in [`stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/stream-graph-admission.ts).
- **Committed-event projection** — Graph records only reference `RuntimeEvent`s that have durably committed to the event log.
- **Supervisor wake timing** — Wakes deliver only after root AgentRun completion, preventing lost or premature notifications.
- **Recovery from logs** — System rebuilds graph state from SQLite rows and Runtime logs, not from in-memory state, enabling crash-safe continuation.

These invariants are verified by the test suite in `packages/runtime/src/__tests__/stream-graph-*.test.ts`.

## Working with the Agent Graph API

### Adding Work to the Graph

To initiate a new operator that runs a specialist agent:

```typescript
import { update_agent_graph } from '@maka/core/graph-command';

// Add a new operator that runs the "local_read" specialist
await update_agent_graph({
  add_work: [
    {
      work_id: 'w1',
      operator_id: null,               // null → provision a new operator
      agent_id: 'local_read',          // catalog agent to spawn
      instruction: 'Inspect storage layout',
      input_ids: [],                   // no upstream records yet
    },
  ],
});

```

This writes to `agent_graph_schedule` via [`packages/core/src/agent-graph-schedule.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-schedule.ts).

### Querying Current Graph State

To inspect operators and ready work:

```typescript
import { view_agent_graph } from '@maka/core/graph-command';

const graph = await view_agent_graph();
console.log('Operators:', graph.operators);
console.log('Ready work IDs:', graph.readyWorkIds);

```

The implementation in [`packages/core/src/graph-command.ts`](https://github.com/apache/maka/blob/main/packages/core/src/graph-command.ts) reads the SQLite control plane and the projection.

### Reading Child Agent Output

To fetch results from a completed child activation:

```typescript
import { agent_output } from '@maka/core/graph-command';

const output = await agent_output({
  childSessionId: 'sess-123',
  runId: 'run-456',
  view: 'result',   // only the final model answer
});
console.log(output.text);

```

This retrieves authoritative `RuntimeEvent` data from the event log.

### Finishing a Schedule

To mark work as complete and stop further admission:

```typescript
await update_agent_graph({
  finish: {
    work_ids: ['w1', 'w2'],   // IDs of records that should be the final answer
  },
});

```

The coordinator stops admission after processing this finish row.

## Key Source Files

| Area | File | Purpose |
|------|------|---------|
| **Control-plane schema** | [`packages/storage/src/agent-graph-control-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-graph-control-store.ts) | SQLite tables for topology, schedule, claims, wakes |
| **Schedule API** | [`packages/core/src/agent-graph-schedule.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-schedule.ts) | `add_work`, `stop`, `finish` definitions |
| **Topology management** | [`packages/core/src/agent-graph-topology.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-topology.ts) | Monotonic operator creation, child-Session linking |
| **Event projection** | [`packages/runtime/src/stream-graph-projection.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-projection.ts) | Turns `RuntimeEvent`s into `AgentGraphRecord`s |
| **Readiness policies** | [`packages/runtime/src/stream-graph-readiness.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-readiness.ts) | `map` and `all_settled` deterministic intents |
| **Admission control** | [`packages/runtime/src/stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-admission.ts) | `runClaimedAgentGraphIntent` exact-once logic |
| **Coordinator loop** | [`packages/runtime/src/stream-graph-dispatch.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-dispatch.ts) | Drive-to-quiescence, concurrent operator execution |
| **Supervisor wakes** | [`packages/runtime/src/agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-supervisor-wake.ts) | Durable wake rows, retry logic |
| **Public API** | [`packages/runtime-host/src/server/agent-graph-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-coordinator.ts) | Exposes `view_agent_graph`, `update_agent_graph`, `agent_output` over RPC |

## Summary

- The **Agent Graph** adds a SQLite control plane to Maka's existing Runtime Host, enabling durable multi-agent scheduling without secondary execution infrastructure.
- **Operators** (child Sessions) and **Activations** (AgentRuns) separate container lifecycle from execution instances.
- The **exactly-once claim** mechanism in [`stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/stream-graph-admission.ts) prevents duplicate work during retries.
- **Graph projections** transform committed `RuntimeEvent`s into records that trigger downstream readiness.
- **Supervisor wakes** provide durable checkpoints for root-Agent oversight without blocking child execution.
- All scheduling state recovers from SQLite and the Runtime Event Log, eliminating dependency on in-memory coordinator state.

## Frequently Asked Questions

### What is the difference between an Operator and an Activation in Maka's Agent Graph?

An **Operator** is a stable child Session container that can be reused across multiple executions, while an **Activation** is a specific AgentRun instance that produces `RuntimeEvent`s. According to [`packages/core/src/agent-graph-topology.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-topology.ts), operators persist across graph revisions, whereas activations represent point-in-time executions within those operators.

### How does the Agent Graph ensure exactly-once execution of tasks?

The graph uses a **claim** mechanism implemented in [`packages/runtime/src/stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-admission.ts). Before executing any intent, the coordinator calls `runClaimedAgentGraphIntent` to pre-allocate Turn/Run IDs and persist the claim to SQLite. If the coordinator crashes and retries, it detects existing claims and skips duplicate execution, ensuring exactly-once semantics.

### Can the Agent Graph recover from coordinator crashes without losing work?

Yes. The architecture recovers by rebuilding state from the **Runtime Event Log** and **SQLite control plane** rather than in-memory state. As documented in [`agent-graph-control-store.ts`](https://github.com/apache/maka/blob/main/agent-graph-control-store.ts), all topology, schedule revisions, and claims are durable. When the coordinator restarts, it replays the append-only schedule log and resumes projections from the last committed event.

### How does the main Agent communicate with child agents in the graph?

The main Agent does not directly message child agents. Instead, it writes schedule revisions via `update_agent_graph`, and the coordinator provisions operators independently. The main Agent reads results asynchronously through `view_agent_graph` and `agent_output` only when a **supervisor wake** indicates the graph has reached a useful checkpoint, preventing the main Agent from becoming a bottleneck.