How to Create Child Agents and Schedulers in Apache Maka

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, returns built-in agent definitions and their corresponding IDs.

// 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, 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.

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

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 is a thin wrapper around setTimeout and clearTimeout that records pending delays for testability.

For testing scenarios, use the ManualScheduler implementation:

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:

// 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 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 provides available definitions, while 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 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, 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. 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.

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