Subagents

Subagents let the model delegate focused work to isolated child agents. Each subagent runs in its own conversation context with its own session, and returns a result to the parent agent.

Why opt-in?

Subagents are disabled by default because each spawned child runs a full conversation loop with its own token budget. Exposing the Agent tool also means the model may choose to delegate work even when a direct approach would be simpler and cheaper. Keeping subagents opt-in avoids the extra tool in context and prevents unintended delegation.

Configuration

import { Agent } from "noumen";
import { LocalSandbox } from "noumen/local";

const code = new Agent({
  provider,
  sandbox: LocalSandbox({ cwd: "/my/project" }),
  options: {
    enableSubagents: true,
  },
});

When enabled, an Agent tool is added that the model can call to spawn subagents.

How it works

1. The model calls the Agent tool with a prompt and optional systemPrompt
2. A child Thread is created with its own session ID
3. The child runs independently, using the same tools and sandbox as the parent
4. The child's final response is returned to the parent as the tool result

Agent tool parameters

{
  prompt: string;          // The task for the subagent
  systemPrompt?: string;   // Optional system prompt override
}

Sync vs async

The Agent tool supports both synchronous (wait for result) and asynchronous (fire and check later) modes. In async mode, the tool returns immediately with the session ID, and the parent can check results later via the task system.

Concurrency

The Agent tool is marked isConcurrencySafe: true, so multiple subagents can be spawned in parallel within a single turn. Each subagent gets its own conversation context and session storage.

SubagentConfig type

interface SubagentConfig {
  prompt: string;
  systemPrompt?: string;
  maxTurns?: number;
  model?: string;
}

Hooks

Subagent lifecycle events are available through the hooks system:

{
  event: "SubagentStart",
  handler: async (input) => {
    // input.sessionId — child session
    // input.parentSessionId — parent session
    // input.prompt — the subagent's task
  },
}

See Hooks for details.