# What Is AgentRun in Apache Maka? A Deep Dive into the Execution Engine

> Explore AgentRun, Apache Maka's core execution engine. Understand its role in agent lifecycle management, tool orchestration, and deterministic recovery for robust AI agent operations.

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

---

**AgentRun is the core execution component in Apache Maka that owns the complete lifecycle of an agent, managing session identity, tool orchestration, and deterministic recovery through checkpointing.**

AgentRun functions as the "brain" inside Maka's Runtime Host, ensuring that every unit of work—whether a tool call, model inference, or user command—executes reliably within its session context. Located directly beneath the `SessionManager` and alongside the `RuntimeKernel`, this component coordinates how agents transition from creation to termination while maintaining immutable state logs for replay and recovery.

## AgentRun Architecture and Placement in the Runtime Stack

In Maka's layered architecture, AgentRun occupies a critical position in the **Runtime Host** stack. The execution flow follows a strict hierarchy: client interfaces (Desktop, TUI, CLI, or Bot) communicate with the Runtime Host, which delegates session management to the `SessionManager`, which in turn instantiates and controls AgentRun instances alongside the `RuntimeKernel`.

According to the architecture diagram in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) (lines 26-34), the relationship is hierarchical:

```

Desktop / TUI / CLI / Bot → Runtime Host → SessionManager → AgentRun + RuntimeKernel

```

This placement ensures that AgentRun receives sanitized, session-scoped input while maintaining direct access to the execution kernel and persistence layers. Unlike the `SessionManager`, which tracks meta-level session state, AgentRun possesses granular control over the active turn and agent-specific execution context.

## Core Responsibilities of AgentRun in Maka

AgentRun manages four critical domains of the execution lifecycle, each implemented in [`packages/core/src/agentRun.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agentRun.ts) and orchestrated through the `RuntimeHost`.

### Session and Turn Identity Management

AgentRun maintains authoritative knowledge of **which session a request belongs to** and **which conversation turn is being processed**. This identity tracking prevents cross-contamination between concurrent sessions and ensures that multi-turn conversations maintain coherent state. The component validates session tokens at initialization and binds all subsequent operations—tool calls, model requests, and logging—to that specific session context.

### Agent Lifecycle Orchestration

The component handles the complete state machine of an agent through explicit lifecycle methods: `start()`, activation, pausing, resuming, and `shutdown()`. When invoked via `AgentRun.start()`, the component initializes the execution environment, allocates resources from the `RuntimeKernel`, and prepares the agent graph for evaluation. The `shutdown()` method ensures graceful termination, flushing pending events to the **Runtime Event Log** and releasing kernel resources.

### Continuation and Crash Recovery

AgentRun implements deterministic execution through **checkpointing and replay** mechanisms. In the event of a crash or interruption, the `AgentRun.resume()` method re-hydrates the agent state from the persisted event log, allowing execution to continue from the exact point of failure. This capability is documented in the *Runtime resume* design specification and implemented through coordination with the `RuntimeHost` singleton, which locates the last persisted state via `RuntimeHost.getInstance()`.

### Tool Orchestration and Event Logging

When an agent requires external capabilities, AgentRun invokes the **Tool Runtime** for executing tool calls such as `search` or `fileRead`. It records both invocations and results in the **Runtime Event Log**, creating an immutable audit trail. This logging serves dual purposes: it enables the recovery mechanisms mentioned above and feeds the `Agent Graph Control Plane`, which schedules dependent work as child sessions.

## How AgentRun Interacts with the Maka Runtime

AgentRun operates as a coordination hub between three distinct subsystems:

- **Input Layer**: Receives scoped requests from `SessionManager` (defined in [`packages/runtime/src/SessionManager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/SessionManager.ts)), which handles session creation and turn tracking before handing off control.

- **Persistence Layer**: Publishes structured events to the `Runtime Event Log`, ensuring that every tool invocation, model response, and state transition is durably recorded for replay and auditing.

- **Scheduling Layer**: Communicates with the **Agent Graph Control Plane** (implemented in [`packages/runtime/src/AgentGraph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/AgentGraph.ts)) to spawn child sessions when the current agent generates dependent work units, enabling complex multi-agent workflows.

This interaction pattern ensures that AgentRun remains stateless with respect to session metadata (handled by SessionManager) while maintaining full authority over execution semantics and tool invocation.

## Working with AgentRun: Practical Code Examples

The following snippets demonstrate idiomatic usage patterns via the Maka SDK, mapping directly to the components described in the architecture.

### Creating and Starting an AgentRun from a CLI Command

This example shows how [`packages/cli/src/commands/run.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/commands/run.ts) instantiates an AgentRun for interactive use:

```typescript
import { AgentRun } from '@maka/core';
import { RuntimeHost } from '@maka/runtime-host';

// Create a runtime host (singleton for the process)
const host = new RuntimeHost();

// A simple CLI entry point
async function main() {
  // Initialise a new session for the current user
  const session = await host.createSession({ user: 'alice' });

  // Start an AgentRun that will handle the upcoming turn
  const agent = await AgentRun.start({
    sessionId: session.id,
    // Optional: provide a tool list the agent may invoke
    tools: ['search', 'fileRead'],
  });

  // Send the user prompt to the agent
  const response = await agent.runTurn({ prompt: 'What is the weather in Berlin?' });

  console.log('Agent response:', response);
  // When finished, gracefully shut down the run
  await agent.shutdown();
}

main().catch(console.error);

```

### Using the AgentRun API from a Bot Integration

For automated integrations, AgentRun provides a lightweight interface that handles session continuity across discrete messages:

```typescript
import { AgentRun } from '@maka/core';
import { BotClient } from '@maka/bot';

const bot = new BotClient();

bot.onMessage(async (msg) => {
  const agent = await AgentRun.start({ sessionId: msg.sessionId });
  const reply = await agent.runTurn({ prompt: msg.text });
  await bot.sendMessage(msg.channel, reply);
  await agent.shutdown(); // clean up after each turn
});

```

### Recovering from a Crash with Runtime Resume

The `AgentRun.resume()` method enables fault-tolerant execution by reconstructing state from the event log:

```typescript
import { RuntimeHost, AgentRun } from '@maka/runtime';

async function resumeAgent(sessionId: string) {
  // RuntimeHost knows how to locate the last persisted state
  const host = RuntimeHost.getInstance();

  // Re‑hydrate the AgentRun from the event log
  const agent = await AgentRun.resume({ sessionId });

  // Continue processing the next turn
  const next = await agent.runTurn({ prompt: 'continue' });
  console.log(next);
}

```

## Key Source Files and Implementation Details

Understanding AgentRun requires familiarity with these specific locations in the Apache Maka repository:

| Component | Source File | Purpose |
|-----------|-------------|---------|
| **AgentRun Core** | [`packages/core/src/agentRun.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agentRun.ts) | Defines the `AgentRun` class, its lifecycle methods (`start`, `runTurn`, `shutdown`, `resume`), and the execution state machine. |
| **Runtime Host** | [`packages/runtime-host/src/RuntimeHost.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/RuntimeHost.ts) | The singleton execution authority that creates sessions, owns the `SessionManager`, and orchestrates AgentRun instances. |
| **Session Management** | [`packages/runtime/src/SessionManager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/SessionManager.ts) | Handles session creation, turn tracking, and delegates execution control to AgentRun. |
| **Agent Graph** | [`packages/runtime/src/AgentGraph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/AgentGraph.ts) | Implements the control plane for scheduling dependent work and child sessions triggered by AgentRun. |
| **CLI Entry Point** | [`packages/cli/src/commands/run.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/commands/run.ts) | Demonstrates the public `maka run` command that instantiates AgentRun for end-user access. |
| **Architecture Docs** | [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) | Contains the system diagram and textual description of AgentRun's position in the execution stack. |

## Summary

- **AgentRun is the execution authority** within Apache Maka's Runtime Host, positioned beneath the `SessionManager` and alongside the `RuntimeKernel`.

- It manages **four critical responsibilities**: session/turn identity, complete agent lifecycle (start to shutdown), crash recovery via checkpointing, and tool orchestration with immutable event logging.

- The component exposes a deterministic API through methods like `AgentRun.start()`, `runTurn()`, and `AgentRun.resume()`, enabling both interactive CLI usage and automated bot integrations.

- All state mutations are persisted to the **Runtime Event Log**, allowing AgentRun to reconstruct exact execution context after failures or interruptions.

- Source code implementation resides primarily in [`packages/core/src/agentRun.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agentRun.ts), with orchestration support from `RuntimeHost` and `SessionManager`.

## Frequently Asked Questions

### What is the difference between AgentRun and SessionManager in Maka?

**SessionManager** handles session creation, user authentication, and turn tracking at the meta level, while **AgentRun** owns the actual execution of an agent within a specific session. The SessionManager decides *which* session should process a request; AgentRun determines *how* that request executes, manages tool calls, and handles the agent's internal state transitions.

### How does AgentRun handle crashes and recovery?

AgentRun implements **deterministic replay** through the `AgentRun.resume()` method. When a crash occurs, the `RuntimeHost` locates the last persisted checkpoint in the Runtime Event Log. AgentRun then re-hydrates its state from this log and continues execution from the exact point of interruption, ensuring no work is lost and side effects remain consistent.

### Can AgentRun execute multiple tools in parallel?

While AgentRun maintains a single execution context per session turn, it coordinates with the **Tool Runtime** to invoke external tools. The current implementation in [`packages/core/src/agentRun.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agentRun.ts) processes tool results sequentially within a turn to ensure deterministic ordering in the event log, though child sessions spawned via the Agent Graph Control Plane can execute concurrent work units.

### Where is the AgentRun class defined in the Apache Maka source code?

The `AgentRun` class is defined in [`packages/core/src/agentRun.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agentRun.ts), which exports the primary interface including `start()`, `runTurn()`, `shutdown()`, and `resume()` methods. The runtime instantiation and lifecycle management are orchestrated through [`packages/runtime-host/src/RuntimeHost.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/RuntimeHost.ts), which serves as the singleton entry point for creating AgentRun instances.