Subagents & Workflows

Agents in the harness can delegate work to child agents, or use workflows to break a complex task into multi-stage, multi-agent orchestration. Both are model-callable tools built on the same subagent and workflow primitives.

Subagent delegation

The subagent tool lets the current agent hand a self-contained task to a child agent. The child works in its own session, so the parent is never polluted by its intermediate steps; the parent receives only the final result.

Foreground vs. background

• Foreground (run_in_background: false): the parent waits for the child to finish before continuing — for when the next action depends on the result;
• Background (run_in_background: true): the call returns a durable subagent id immediately, the parent keeps working, and a notice delivers the outcome when the child settles.

Background is the recommended default: start independent delegations together in one message and keep doing useful work while they run; choose foreground only when your next action depends on the result.

Continuable children

A background child keeps its own conversation. The parent can send it more work with send_message, which opens a new turn; list_agents lists continuable children and their status (running actively working, idle loaded but between turns, ready storage-only and resumable); interrupt_agent requests stopping a child's current turn — queued messages stay parked, agents it started keep running, and the child itself stays available for follow-ups.

Two kinds of children

The delegation provider decides whether the child inherits the parent conversation:

• spawn (fresh): the child does not inherit parent context, so its prompt must be self-contained;
• fork: the child starts from the parent's completed history, for follow-up analysis or review that builds on this conversation.

A deployment can mount other providers — out-of-process ACP, real Codex or Claude Code children, and more; which surface is exposed depends on the composition.

Depth cap

Delegation has an absolute depth cap maxDepth, defaulting to 3 (0 forbids delegation). At the cap the subagent tool stays visible, but each attempted start returns an errored result.

Workflows

For large, multi-agent collaborations, use the workflow tool: the agent writes a JavaScript orchestration script that fans work out across many subagents, runs phases, and collects structured results.

Scripts run one subagent with agent(prompt, opts), push each item through stages with pipeline(items, ...stages), run thunks concurrently with parallel(thunks), and report progress with phase() and log(); the script ends with return <value>, which becomes the tool result.

Ralph loops

The ralph tool runs a fixed foreground workflow: toward one immutable objective it starts a sequence of fresh child agents (one per Ralph round), using the shared workspace as long-term memory and one bounded structured handoff (status, summary, evidence, next steps, blocker text) to carry state between rounds.

Ralph is for when the user explicitly asks for a Ralph loop or fresh-agent iteration. Completion and blockers are worker reports, not independent evaluation; use goals for ordinary long-running objectives (see Skills & Goals), and plain subagents or workflows for bounded delegation and fan-out.

Next steps

• Drive one long-running objective automatically: the goals in Skills & Goals.
• The underlying mechanisms live in the developer guide.