# How to Create Child Agents and Schedulers in Apache Maka

> Learn to create child agents and schedulers in Apache Maka using agent_spawn tool. Manage timers retries and cron tasks efficiently with Maka's scheduler.

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

---

**Apache Maka creates child agents through the `agent_spawn` tool and manages deferred work via a Runtime Host-owned scheduler that handles timers, retries, and cron-like tasks.**

Apache Maka runs every task inside a **Runtime Host** that orchestrates execution through isolated sessions and time-driven components. When you need to spawn sub-tasks or schedule recurring work, you must create child agents and configure the schedulers that drive them. This article explains the complete lifecycle based on the actual implementation in the Apache Maka repository.

## Understanding the Runtime Host Architecture

Every operation in Apache Maka executes within a **Runtime Host** that owns a single **scheduler**. This scheduler is the time-driven component responsible for firing timers, retries, and back-off loops for any work that needs to happen later. When you spawn a **child (sub) agent**, you create a sandboxed session that inherits the parent’s permissions, privacy settings, workspace, and skill catalog, but executes in complete isolation.

The child agent creation flow follows four distinct steps: discovery via the agent catalog, definition selection, session spawning through the Runtime Host, and progress monitoring via event streams.

## How to Create Child Agents in Apache Maka

### Discover Available Agents with agent_list

Before spawning a child, you must discover which agent definitions are available. The `agent_list` tool, exposed by the **Agent Catalog** in [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts), returns built-in agent definitions and their corresponding IDs.

```typescript
// List available child agents
const list = await runtime.callTool('agent_list', {
  pageSize: 8,
});

// Select the subagent_id (e.g., "local_read")
const subagentId = list.results[0].subagent_id;

```

The `subagent_id` field is the preferred identifier for spawning, though you can also reference built-in profiles through the `profile` field.

### Spawn Isolated Sessions with agent_spawn

Once you have a definition ID, invoke the `agent_spawn` tool to create the child. According to the implementation in [`packages/runtime/src/subagent-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/subagent-tools.ts), this tool validates the requested `write_back` mode and `isolation` level against the selected definition before calling `ctx.spawnChildSession`—the Runtime-Host-provided capability that actually instantiates the sandboxed session.

```typescript
// Spawn the child with a bounded task
await runtime.callTool('agent_spawn', {
  subagent_id: subagentId,
  task: 'Summarize the latest 5 Git commits in this repository.',
  write_back: 'summary',        // validated against definition capabilities
  isolation: 'same_workspace',  // alternative: 'worktree' for full isolation
});

```

### Monitor Child Execution via Event Streams

After spawning, the parent receives a `ChildAgentProgressProjector` that streams the child’s stdout and status events in real time. When the child finishes execution, you can retrieve its final output using the `agent_output` tool. This separation of concerns ensures that long-running child tasks do not block the parent session while maintaining full observability.

## Configuring Schedulers in Apache Maka

### Host-Level Task Scheduling

For cron-like recurring work, Apache Maka uses the **Scheduled Task Coordinator** located in [`packages/runtime-host/src/server/scheduled-task-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/scheduled-task-coordinator.ts). When a `ScheduledTask` catalog entry is loaded, the Runtime Host constructs a `Scheduler` instance that owns a queue of timers and runs an **idle retention** loop to keep the scheduler alive. This coordinator guarantees that all pending timers are flushed before the host shuts down, preventing data loss for in-flight retries.

You define scheduled tasks using the `ScheduledTaskCatalog` interface:

```typescript
import { ScheduledTaskCatalog } from '@maka/core/scheduled-task';

const hourlyTask: ScheduledTaskCatalog = {
  id: 'hourly-summary',
  cron: '0 * * * *',  // every hour, on the hour
  description: 'Generate a summary of recent activity',
  tool: { 
    name: 'agent_spawn', 
    parameters: { 
      subagent_id: 'local_read', 
      task: 'Summarize recent activity.' 
    } 
  },
};

// Register with the Runtime Host
await runtimeHost.scheduleTask(hourlyTask);

```

### Ad-Hoc Timing with GoalContinuation

For one-off timeouts and retry logic within a specific goal, you can inject a **scheduler** implementation into the `GoalContinuation` machinery. The default `GoalContinuationScheduler` in [`packages/runtime/src/goal-continuation.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/goal-continuation.ts) is a thin wrapper around `setTimeout` and `clearTimeout` that records pending delays for testability.

For testing scenarios, use the `ManualScheduler` implementation:

```typescript
import { ManualScheduler } from '@maka/runtime/__tests__/goal-continuation.test';

const scheduler = new ManualScheduler();  // exposes pendingDelays(), fireNext()
const continuation = new GoalContinuation({ scheduler });
await continuation.runGoal(myGoal);

```

## Practical Implementation Examples

**Spawning a child agent with full workflow:**

```typescript
// 1️⃣  Discover
const list = await runtime.callTool('agent_list', { pageSize: 8 });
const subagentId = list.results[0].subagent_id;

// 2️⃣  Spawn with validation
await runtime.callTool('agent_spawn', {
  subagent_id: subagentId,
  task: 'Analyze dependencies in package.json',
  write_back: 'analysis',
  isolation: 'worktree',  // Full workspace isolation
});

// 3️⃣  Output is available via agent_output when complete

```

**Creating a scheduled task that retries on failure:**

The scheduler automatically backs off and retries failed operations, preserving a deterministic log of each attempt. Define the retry policy in the `ScheduledTask` configuration and let the coordinator in [`scheduled-task-coordinator.ts`](https://github.com/apache/maka/blob/main/scheduled-task-coordinator.ts) handle the execution cadence.

## Summary

- **Child agents** provide sandboxed execution contexts that inherit parent permissions but isolate workspace pollution, created via `agent_spawn` and tracked through `ChildAgentProgressProjector`.
- The **agent_list** tool in [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts) provides available definitions, while [`packages/runtime/src/subagent-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/subagent-tools.ts) handles the spawn validation and session creation.
- **Schedulers** exist at two levels: the host-level `Scheduler` in [`packages/runtime-host/src/server/scheduled-task-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/scheduled-task-coordinator.ts) manages cron-like tasks and idle retention, while `GoalContinuationScheduler` handles ad-hoc timeouts.
- All schedulers guarantee graceful shutdown by flushing pending timers, ensuring reliable retry and back-off loops for transient failures.

## Frequently Asked Questions

### How do child agents inherit permissions from their parent?

Child agents inherit the parent’s **permissions, privacy settings, workspace, and skill catalog** automatically upon creation through the `ctx.spawnChildSession` mechanism. However, the isolation level (controlled via the `isolation` parameter in `agent_spawn`) determines whether the child operates in the `same_workspace` or a separate `worktree`, affecting filesystem visibility while maintaining security boundaries.

### What happens to scheduled tasks when the Runtime Host shuts down?

The **Scheduled Task Coordinator** implements an idle retention loop that keeps the scheduler alive while work is pending. According to the implementation in [`packages/runtime-host/src/server/scheduled-task-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/scheduled-task-coordinator.ts), the coordinator guarantees that all pending timers are flushed before the host shuts down, ensuring that scheduled tasks and retries complete or safely persist their state for the next startup.

### Can I customize the scheduler for testing retry logic?

Yes. Instead of the default `GoalContinuationScheduler`, you can inject a `ManualScheduler` (available in the runtime test utilities) into the `GoalContinuation` constructor. This implementation exposes `pendingDelays()` and `fireNext()` methods, allowing deterministic control over timeout execution in unit tests without relying on actual system time.

### What is the difference between `write_back` modes in child agents?

The `write_back` parameter in `agent_spawn` specifies how the child agent persists its results. The tool validates this mode against the capabilities defined in the agent catalog entry at [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts). Common modes include streaming results back to the parent session or writing to specific output channels, though the exact available modes depend on the specific `subagent_id` definition.