Subagents

A subagent is another published Agent referenced from an Agent's recursive subagents tree. It is not a separate primitive or a special session profile.

The parent remains responsible for the overall interaction. It delegates a focused task, the child runs in a bounded execution context, and the result returns to the parent.

Where subagents are defined

The authoritative subagent tree is part of the published Agent revision. Each node references another Agent by slug and optional version pin.

A node can add:

an alias;
extra Skills;
extra Tools;
appended instructions;
a model override;
permission narrowing;
recursive children;
structural runtime limits.

Invocation overlays can refine the launch where the contract allows, but they do not create a second profile-based composition model and cannot broaden authority beyond the published and policy-controlled ceilings.

Model resolution

A subagent can:

inherit the parent invocation's resolved model behavior;
carry a concrete model override;
route through a model strategy such as utility, review, or planning.

Model resolution happens at invocation boundaries, including subagent spawn. The selected model does not change unpredictably in the middle of a turn.

Runtime limits

An Agent can declare limits for its recursive work:

maximum depth;
maximum concurrent fan-out;
maximum total spawns;
optional token budget where supported by the launching runtime.

Depth, fan-out, and spawn limits are enforced by the runtime. They are not advisory text in the system prompt.

In Interactive Sessions

The session resolves the published Agent revision and its full recursive tree at launch. The parent can delegate through its task capability. Session events record the parent tool call and child execution lifecycle so the work remains inspectable.

The Session supplies real-time conversation, workspace, thread, and lifecycle behavior; the Agent supplies the composition.

In Workflows

The xema/agent action names the primary Agent with agentRef. Its current action contract also supports per-step subagent bindings and coordinator limits where a Workflow needs a narrower or more explicit launch envelope.

yaml

1jobs:
2  investigate:
3    uses: xema/agent
4    with:
5      agentRef: incident-coordinator@3
6      deliverableSpecRef: incident-report@1
7      agentContext:
8        prompt: Investigate the incident and return a verified action plan.
9      subAgents:
10        - slug: policy-researcher
11          modelOverride:
12            kind: strategy
13            modelLane: light
14      composition:
15        limits:
16          maxDepth: 3
17          maxSpawns: 12

Platform agent roster

The subagents base biome ships the standard set of platform agents that standard distributions select. Agents marked subagent are meant to be delegated to by another agent; primary agents can lead a session or workflow step, or be used as a subagent too.

Agent	Mode	What it is for
`build`	primary	The interactive default: reads, edits, runs builds and commits in the workspace, and routes to a more specialised delegate when one fits.
`coder`	primary	Implements, refactors, debugs and verifies code; composition instructions add the domain.
`general-purpose`	primary	Balanced assistant for tasks with no narrower specialty.
`planner`	primary	Planning lead: writes a plan or analysis document and coordinates specialists. It does not implement code or run shell commands.
`explorer`	primary	Read-only discovery of an unfamiliar workspace.
`reviewer`	primary	Generic reviewer: judges any deliverable against a brief supplied by the caller and emits a structured verdict (see reviewer-output).
`plan`	subagent	Reads code and returns an ordered step list with files to touch, risks and verification checkpoints. Never edits.
`explore`	subagent	Maps a codebase and answers "where is X done?" with paths and snippets. Read-only.
`kb-researcher`	subagent	Internal research across the knowledge base, artifact store, project registry, backlog, audit log, rules and in-repo code; returns a cited answer.
`web-explorer`	subagent	Fresh public-web research with citations.
`review-assistant`	subagent	Read-only advisory review in an interactive session. It returns findings in chat and has no gate side effects.
`build-verifier`	subagent	Read-only execution of build, type-check and lint commands with structured results.
`impact-analyst`	subagent	Maps the system-wide effects of a proposed change, with risk and mitigation.
`standards-discoverer`	subagent	Synthesises project conventions from the knowledge base, templates, configs and code patterns.
`manifest-reconciler`	subagent	Updates project manifest sections from phase artifacts.
`design-system`	subagent	Owns the workspace visual identity through the `DESIGN.md` format, and exports the theme other agents consume.
`script-goal-solver`	subagent	Takes an intent in natural language, writes and runs the scripts it needs, and returns the result.

The biome also ships the tool profiles these agents use and the skills they consume (code review, build verification, git workflow, knowledge research, markdown editing, monorepo patterns, project standards discovery, test writing and design-system authoring), along with two model lanes, review and creative.

Output surface inspector

The output-surface-inspector subagent, shipped by its own base biome, diagnoses how an app actually behaves in a browser. A main agent delegates to it, or you summon it with @output-surface-inspector. It is strictly read-only: it never edits app code, and fixes go back to the main agent.

It has one tool, inspect_output_surface, which runs a batch of steps in a browser: navigate, reload, click, fill, type, select, press, hover, snapshot, evaluate, console, network, page and wait. A navigate or reload step is a barrier, and later steps in the batch run on the new page. Each batch picks one of two browsers:

Target	What it drives
`user-tab` (default)	Your own live output-surface tab. You see every navigation and click as it happens, and it cannot leave the project's origin. Changes the main agent makes appear in the tab as they are saved, so a fix can be checked by inspecting again.
`headless`	The platform's governed headless browser, for pages that are not your output surface, such as a third-party site or a deployed URL. The first step must be `navigate` with an absolute URL. It is read-only, with GET requests only, so a step that would submit a form fails instead of changing anything. It also needs an agent reach tier that allows broad reach.

The inspector writes what it did and observed (console errors, failed requests, broken UI, and file paths where it can name them) to inspections/<short-slug>.md in the workspace, and ends its turn with exactly one outcome: an INSPECTION REPORT with the path to that file, or NEEDS INPUT when it is blocked. Common blocks are output-surface-not-open (open the output surface) and off-domain (the tab left the project); in both cases it first tries the same investigation in the headless browser if the page is reachable by URL.

Good subagent design

Use subagents for bounded specialist work: research, verification, synthesis, comparison, or provider-specific analysis. Keep shared mutable state and broad orchestration with the parent or a durable Workflow.

Previous: ← API Reference Next: Agent Step in the DSL →