Subagent

Purpose

Subagents let the parent agent delegate tasks that are “independently handled, context-heavy, or parallelizable”, preventing the main thread from bloating.
Each subagent is a temporary HarnessAgent (or remote stub) instance with its own sub-session; results are returned via tool output.

When Subagents Are Enabled

HarnessAgent.build() only loads subagent capability when all of the following are true:

The current agent is not a leaf subagent
disableSubagents() has not been called
model is configured

When satisfied, SubagentsHook (priority=80) is registered and exposes:

agent_spawn / agent_send / agent_list
task_output / task_cancel / task_list

On every PreReasoningEvent turn, SubagentsHook injects into SYSTEM:

Subagent usage rules
List of currently available agent_ids
Summary of async tasks in the current session (up to 10)

Declaration Sources

buildSubagentEntries(...) merges four sources:

Built-in general-purpose
Programmatic declarations: builder.subagent(SubagentDeclaration)
File declarations: workspace/subagents/*.md (loaded non-recursively by AgentSpecLoader)
Custom factories: builder.subagentFactory(name, factory) or builder.subagentFactory(name, description, factory) to give the orchestrator a meaningful description instead of the bare name (falls back to the name when omitted or blank)

Declaration Model (`SubagentDeclaration`)

SubagentDeclaration supports 3 mutually exclusive source modes:

Definition workspace mode
- workspace(path) points to a definition directory (typically containing AGENTS.md)
Inline mode
- inlineAgentsBody(...) is used directly as the system prompt base
Remote HTTP mode
- url(...) + optional headers(...), execution delegated remotely via the task protocol

Mutual exclusion constraints (validated on build()):

url cannot coexist with workspace or non-empty inlineAgentsBody
workspace and non-empty inlineAgentsBody cannot coexist

Runtime Workspace Five-Row Decision Table

WorkspaceMode determines the runtime workspace root:

Case	sysPrompt base source	Runtime workspace
Built-in `general-purpose` (always SHARED)	No additional base (only Subagent Context appended; `AGENTS.md` still injected by WorkspaceContextHook)	`mainWorkspace`
`workspace.path` + `ISOLATED`	`<workspace.path>/AGENTS.md` (empty if absent)	`workspace.path`
`workspace.path` + `SHARED`	`<workspace.path>/AGENTS.md` (empty if absent)	`mainWorkspace`
No `workspace.path` + `ISOLATED` (default)	`inlineAgentsBody` / markdown body	`mainWorkspace/agents/<name>/workspace` (auto-created)
No `workspace.path` + `SHARED`	`inlineAgentsBody` / markdown body	`mainWorkspace`

Notes:

tools is an allowlist for inherited tools: it only filters the parent toolkit, and does not affect tools the subagent auto-registers locally
Multiple declarations can reuse the same definition workspace
workspace.path relative paths are resolved via mainWorkspace.resolve(...).normalize()

Declaration Files (`workspace/subagents/<id>.md`)

The filename (without .md) is the agent_id; name is not read from front matter.

---
description: Code review expert
workspace:
  mode: isolated               # isolated | shared, defaults to isolated
  path: ./defs/reviewer        # optional; relative to mainWorkspace or absolute
model: openai:gpt-4o-mini      # optional
maxIters: 8                    # optional, default 10
tools: [read_file, grep_files] # optional
---

You are a subagent focused on code review.

Parsing rules (AgentSpecLoader):

Required: description
Only scans the first level of subagents/ directory for .md files (non-recursive)
If workspace.path is set and body is non-empty: logs a warning; body is ignored
Markdown declarations currently do not parse url/headers (remote declarations should use the programmatic API)

Programmatic Configuration

HarnessAgent.builder()
    .name("orchestrator")
    .model(model)
    .workspace(workspace)
    .subagent(SubagentDeclaration.builder()
        .name("reviewer")
        .description("Code review expert")
        .workspace(Path.of("./defs/reviewer"))
        .workspaceMode(WorkspaceMode.ISOLATED)
        .model("qwen3-max")
        .maxIters(8)
        .tools(List.of("read_file", "grep_files"))
        .build())
    .subagent(SubagentDeclaration.builder()
        .name("remote-researcher")
        .description("Remote research subagent")
        .url("http://agent-task-server:8080")
        .headers(Map.of("Authorization", "Bearer xxx"))
        .build())
    .build();

Built-in `general-purpose`

The built-in general-purpose requires no declaration file and is always included in the entry list.
Its goal is to “mirror the parent agent’s capabilities”:

Shares the main workspace (SHARED semantics)
Inherits and mirrors the parent agent’s:
- toolkit (parent tools)
- hooks
- execution config
- compaction / toolResultEviction
- additional context files / maxContextTokens
- various disable flags
Always a leaf subagent (cannot further spawn subagents)

Recursion Prevention and Depth Safety

Two safety mechanisms:

All subagents generated via declarations or built-in are given asLeafSubagent() — leaf agents do not register SubagentsHook
AgentSpawnTool also has a dynamic depth cap: MAX_SPAWN_DEPTH = 3

RuntimeContext Propagation

When agent_spawn / agent_send invokes a subagent:

The sub-session session_id is a new value (sub-<uuid>)
userId is propagated from the parent RuntimeContext to the child RuntimeContext

This maintains consistent USER-dimension isolation keys (e.g., scenarios where namespace/sandbox isolation depends on userId).

Tool Reference and Key Parameters

Tool	Purpose	Key Parameters
`agent_spawn`	Create a subagent; optionally execute the first task sync or async	`agent_id` required; `task` optional; `label` optional; `timeout_seconds` default 30, `0` = background, max 600
`agent_send`	Send a follow-up message to an existing subagent	`agent_key` or `label` (one required); `message` required; `timeout_seconds` same rules
`agent_list`	List currently active subagents	none
`task_output`	Query / wait for background task result	`task_id`; `block` (default true, use false to poll status); `timeout` default 30000ms, max 600000ms
`task_cancel`	Cancel a task	`task_id`
`task_list`	List tasks in the current session	`status_filter` (running/completed/failed/cancelled/all)

Notes:

The agent_key for agent_send must be the complete agent_key: ... from the agent_spawn return value (not agent_id / session_id / task_id)
Do not immediately poll after creating an async task; prefer returning to the user first, then using task_output(block=false) or task_list to check latest status

Async Task Lifecycle and Storage

By default, the parent agent uses WorkspaceTaskRepository (unless overridden with taskRepository(...)). Lifecycle (simplified):

putTask(...) writes TaskRecord(PENDING) to workspace
Submits local execution future (local or remote)
Updates to RUNNING during execution
Writes COMPLETED / FAILED / CANCELLED on completion

Storage layering:

In-memory layer: localTasks (node-local acceleration handle, lost on restart)
Persistent layer: agents/<parentAgentId>/tasks/<sessionId>.json (source of truth)

Distributed Semantics

Task execution is sticky to the creating node, but any node can read state through the workspace
task_output(block=true) degrades gracefully in cross-node scenarios and does not block indefinitely
task_cancel persists cancelRequested=true; the executing node polls this flag and aborts
The orphan sweeper marks local tasks with no heartbeat for a long time as FAILED (remote transport tasks are not subject to this check)

Relationship to filesystem mode:

Mode	`agents/<agentId>/tasks/` path visibility
`RemoteFilesystemSpec`	Routed to shared remote storage, visible to multiple nodes
`SandboxFilesystemSpec`	Goes through sandbox filesystem and sandbox state persistence
`LocalFilesystemSpec` / local default	Visible on local machine only

Remote Subagent Behavior

When a declaration has url(...) configured:

The factory returns a RemoteSubagentStub (placeholder, performs no local reasoning)
Actual execution is delegated to a remote task HTTP service via TaskRunSpec.RemoteTaskRunSpec + AgentProtocolTaskClient
Supports both synchronous (timeout_seconds > 0) and asynchronous (timeout_seconds = 0) modes

Practical Advice

Write description clearly — “when to use / output format / prohibited actions” — this is the key signal the parent model uses to decide whether to delegate
Subagent maxIters is typically set smaller than the parent agent to avoid sub-threads consuming excessive tokens
After session compaction or recovery, first use task_list() to restore full task state before making single-task queries

Quick Start

Features

Multi Agent

Harness

Purpose

When Subagents Are Enabled

Declaration Sources

Declaration Model (`SubagentDeclaration`)

Runtime Workspace Five-Row Decision Table

Declaration Files (`workspace/subagents/<id>.md`)

Programmatic Configuration

Built-in `general-purpose`

Recursion Prevention and Depth Safety

RuntimeContext Propagation

Tool Reference and Key Parameters

Async Task Lifecycle and Storage

Distributed Semantics

Remote Subagent Behavior

Practical Advice

​Purpose

​When Subagents Are Enabled

​Declaration Sources

​Declaration Model (SubagentDeclaration)

​Runtime Workspace Five-Row Decision Table

​Declaration Files (workspace/subagents/<id>.md)

​Programmatic Configuration

​Built-in general-purpose

​Recursion Prevention and Depth Safety

​RuntimeContext Propagation

​Tool Reference and Key Parameters

​Async Task Lifecycle and Storage

​Distributed Semantics

​Remote Subagent Behavior

​Practical Advice

​Related Pages

Purpose

When Subagents Are Enabled

Declaration Sources

Declaration Model (`SubagentDeclaration`)

Runtime Workspace Five-Row Decision Table

Declaration Files (`workspace/subagents/<id>.md`)

Programmatic Configuration

Built-in `general-purpose`

Recursion Prevention and Depth Safety

RuntimeContext Propagation

Tool Reference and Key Parameters

Async Task Lifecycle and Storage

Distributed Semantics

Remote Subagent Behavior

Practical Advice

Related Pages