How the Agent Graph in Mako Enables Declarative Scheduling

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) 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) 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) 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) 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) 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:

// 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:

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, 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 – Defines the durable epoch identifier and primitive operations for advancing, binding, or rejecting epochs.
• 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 – Declarative representation of time-based triggers that the scheduler monitors.
• 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 – Orchestrates admission, execution, and retirement of graph instances.
• 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 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) 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) 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.

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