# How the Agent Graph in Mako Enables Declarative Scheduling

> Discover how the Mako Agent Graph transforms declarative goals into a persistent execution graph. It automates retries and ordering for reliable, exactly-once task execution.

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

---

**The Agent Graph in Mako translates declarative descriptions of work—goals, scheduled tasks, and dependencies—into a durable, persistent execution graph that automatically manages retries, ordering, and exactly-once semantics without imperative polling loops.**

Mako (apache/maka) is an open-source framework for building reliable multi-agent systems. At its heart lies the **Agent Graph**, a core abstraction that separates *what* should happen from *how* it is coordinated. Instead of writing imperative code that polls queues or manages state machines, developers declare intents through `Goal` and `ScheduledTask` objects. The Agent Graph runtime materializes these declarations into a concrete graph of *turns* that are executed, retried, and persisted across process restarts.

## Core Architecture of the Agent Graph

The Agent Graph architecture consists of several durable primitives that work together to guarantee reliable execution. These components are implemented across the `@maka/core` and `@maka/runtime-host` packages.

### Agent Graph Epoch

The **Agent Graph epoch** ([`packages/core/src/agent-graph-epoch.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-epoch.ts)) serves as a durable identifier for a single "lifetime" of a graph within a root Session. It tracks execution progress and ensures each turn is processed exactly once. The epoch advances atomically via `AgentGraphEpoch.advance`, persisting state transitions to survive crashes or restarts.

### Supervisor Wake

The **supervisor wake** mechanism ([`packages/core/src/agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-supervisor-wake.ts)) implements a durable "wake-up" request that binds a graph-safe execution identity to a root Session turn. This guarantee ensures that only one wake can schedule a graph at any given time, preventing race conditions and duplicate execution.

### Scheduled Task

The **ScheduledTask** class ([`packages/core/src/scheduled-task.ts`](https://github.com/apache/maka/blob/main/packages/core/src/scheduled-task.ts)) provides a declarative construct for time-based triggers. Rather than implementing cron loops, developers declare timestamps or expressions. The graph scheduler watches these tasks and automatically injects a supervisor wake when triggers fire.

### Goal

The **Goal** class ([`packages/core/src/goal.ts`](https://github.com/apache/maka/blob/main/packages/core/src/goal.ts)) represents the top-level declarative intent—for example, "coordinate this task through a hosted Agent Graph." Creating a Goal instantiates a new Agent Graph epoch and establishes the root of the execution graph.

### Runtime Host Coordinator

The **runtime-host coordinator** ([`packages/runtime-host/src/server/agent-graph-execution-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-execution-coordinator.ts)) bridges the durable Agent Graph read-model with the live Host execution engine. It handles admission of new graphs, retirement of completed goals, and recovery of interrupted turns.

## Declarative Scheduling Execution Flow

When you use the Agent Graph in Mako for declarative scheduling, the following sequence occurs without requiring explicit polling or loop management:

1. **Declare a Goal** – Client code instantiates a `Goal` object describing the desired work.
2. **Attach Conditions (Optional)** – A `ScheduledTask` is attached to specify future timestamps or cron-like triggers.
3. **Submit to Runtime Host** – The Goal is transmitted to the Runtime Host via the Agent Graph client.
4. **Supervisor Wake Persistence** – The host stores an `AgentGraphSupervisorWake` that binds the graph's epoch to the root Session turn.
5. **Epoch Advancement** – Each executed turn advances the epoch via `AgentGraphEpoch.advance`, persisting the new state durably.
6. **Automatic Trigger Execution** – When a scheduled task's condition becomes true, the scheduler generates a new wake, inserting a turn that executes the declared action.
7. **Graph Retirement** – Upon Goal completion or cancellation, the **Agent Graph retirement coordinator** cleans up resources and finalizes the epoch.

## Implementing Declarative Scheduling in Code

The following examples demonstrate how to leverage the Agent Graph for durable, declarative scheduling in TypeScript.

### Declaring Goals and Scheduled Tasks

This snippet creates a Goal with a time-based trigger and submits it to the Runtime Host:

```typescript
// 1️⃣ Create a Goal – the top-level declarative intent
import { Goal } from '@maka/core';
const myGoal = new Goal({
  description: 'Coordinate this task through a hosted Agent Graph.'
});

// 2️⃣ Attach a scheduled task (e.g., run in 5 minutes)
import { ScheduledTask } from '@maka/core';
const task = new ScheduledTask({
  runAt: Date.now() + 5 * 60_000, // 5 minutes from now
  action: async () => {
    // This code runs when the task fires
    console.log('Task triggered inside Agent Graph');
  }
});
myGoal.addTask(task);

// 3️⃣ Submit the Goal to the Runtime Host
import { RuntimeHostClient } from '@maka/runtime-host';
await RuntimeHostClient.submitGoal(myGoal);

```

Internally, the host creates an `AgentGraphSupervisorWake`, persists an initial `AgentGraphEpoch`, and—when the timeout expires—the scheduler injects a new turn that executes the `action` callback.

### Inspecting Graph Execution

You can verify that declarative steps materialized as concrete turns by querying the durable read-model:

```typescript
import { AgentGraphClient } from '@maka/runtime-host';
const epochPages = await AgentGraphClient.collectEpochPages({
  rootSessionId: myGoal.sessionId,
  direction: 'newest-first'
});
console.log(epochPages);

```

The `collectEpochPages` API, implemented in [`packages/runtime-host/src/server/agent-graph-reader.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-reader.ts), returns a chronological list of graph epochs, providing observability into how declarative intents translated into executed turns.

## Key Source Files and Components

Understanding the following source files is essential for working with the Agent Graph in Mako:

- **[`packages/core/src/agent-graph-epoch.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-epoch.ts)** – Defines the durable epoch identifier and primitive operations for advancing, binding, or rejecting epochs.
- **[`packages/core/src/agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-supervisor-wake.ts)** – Implements the wake mechanism that couples graph epochs to root Session turns with exclusive scheduling guarantees.
- **[`packages/core/src/scheduled-task.ts`](https://github.com/apache/maka/blob/main/packages/core/src/scheduled-task.ts)** – Declarative representation of time-based triggers that the scheduler monitors.
- **[`packages/core/src/goal.ts`](https://github.com/apache/maka/blob/main/packages/core/src/goal.ts)** – High-level entry point for defining what the Agent Graph should accomplish.
- **[`packages/runtime-host/src/server/agent-graph-execution-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-execution-coordinator.ts)** – Orchestrates admission, execution, and retirement of graph instances.
- **[`packages/runtime-host/src/server/agent-graph-reader.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-reader.ts)** – Provides read access to durable graph state via methods like `collectEpochPages`.

## Summary

- The **Agent Graph in Mako** converts declarative intent into durable execution graphs, eliminating the need for manual polling or state management.
- **Agent Graph epochs** provide exactly-once execution guarantees by tracking progress through durable identifiers that survive process restarts.
- **Supervisor wakes** ensure exclusive scheduling, binding graph execution to specific Session turns without race conditions.
- **ScheduledTask** and **Goal** classes allow developers to declare *when* and *what* should execute, while the runtime handles *how* and *where*.
- The **Runtime Host coordinator** automatically advances graphs, retries failed turns, and retires completed goals.

## Frequently Asked Questions

### What is an Agent Graph epoch in Mako?

An **Agent Graph epoch** is a durable identifier defined in [`packages/core/src/agent-graph-epoch.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-epoch.ts) that represents a single "lifetime" of a graph within a root Session. It tracks execution progress and provides the `advance` method to atomically persist state transitions, ensuring that each turn is processed exactly once even across process restarts.

### How does the supervisor wake ensure exactly-once execution?

The **supervisor wake** ([`packages/core/src/agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-supervisor-wake.ts)) creates a durable binding between a graph epoch and a root Session turn. By guaranteeing that only one wake can schedule a graph at any time, it prevents duplicate scheduling. Combined with epoch advancement, this ensures that work items execute exactly once regardless of failures or retries.

### Can I schedule recurring tasks with the Agent Graph?

Yes. While the `ScheduledTask` class supports single future timestamps, the declarative scheduling model allows multiple tasks to be attached to a single Goal. For recurring patterns, you can dynamically generate subsequent `ScheduledTask` instances within action callbacks or leverage cron-like expressions that the scheduler evaluates to generate new wakes automatically.

### How does Mako handle Agent Graph recovery after restarts?

The Agent Graph persists all state—the current epoch, pending wakes, and scheduled tasks—to durable storage. Upon restart, the **Runtime Host coordinator** ([`packages/runtime-host/src/server/agent-graph-execution-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/agent-graph-execution-coordinator.ts)) reloads incomplete epochs from the read-model, identifies pending supervisor wakes, and resumes execution from the last committed state. This design ensures that declared goals survive process crashes and continue execution without manual intervention.