Subagents

A subagent is a specialised helper that an agent step’s main agent can delegate to while it works: a test writer, a security reviewer, a documentation checker. Each subagent has its own system prompt, tool allowlist and model. Subagents are defined once per pipeline and attached to individual agent steps.

This is different from a separate pipeline step. A step runs on its own, in order, and passes output through templates. A subagent is invoked by the agent inside a single step, when it decides the subagent’s description fits the task (for Claude Code, through its Task tool).

Defining subagents

In Pipeline settings → Subagents, click Add subagent. A new subagent starts as a read-only reviewer (reviewer, tools Read, Grep, Glob) that you can edit.

UI label	JSON	Required	Notes
Name	id	yes	Lowercase letters, digits and -, starting with a letter. The main agent refers to it by this name. Other characters are converted to - as you type. Renaming updates the steps that use it.
Model	model	no	An alias (sonnet, opus, haiku) or a model id. Empty (“inherit”) uses the step’s model.
When to use	description	yes	The main agent reads this to decide when to delegate. Be specific: “Writes focused unit tests for new code. Use after implementing a change.”
Tools	tools	no	Comma-separated tool names, e.g. Read, Grep, Glob, Bash. Empty (“all tools”) inherits every tool.
System prompt	prompt	yes	The subagent’s instructions. It’s a template: it can use {{issue.*}}, {{vars.*}} and so on, rendered with the context of the step that uses it.

Remove deletes a subagent and detaches it from every step.

Attaching subagents to a step

Select an agent step. Its Subagents section shows a chip per pipeline subagent; click to attach or detach. In JSON, list the ids on the step:

{ "id": "implement", "type": "agent", "harnessId": "claude-code", "subagents": ["test-writer", "security-check"], "…": "…" }

If there are no subagents yet, the section links to Pipeline settings.

Which harnesses support them

Subagents are passed only to harnesses that have Subagent arguments configured on the Harnesses page:

• Claude Code (built-in) passes them with --agents {{subagents}}.
• Other built-in harnesses have no subagent arguments and ignore subagents. The step log shows <harness> has no subagent flag configured; ignoring subagents …, and the editor warns “… has no subagent arguments configured, so these subagents will be ignored.”
• A custom harness (or an edited built-in) can opt in by setting Subagent arguments.

{{subagents}} renders to a JSON object keyed by subagent name, the format Claude Code’s --agents flag takes. tools and model are omitted when empty:

{
  "test-writer": {
    "description": "Writes focused unit tests for new code. Use after implementing a change.",
    "prompt": "You write minimal, meaningful unit tests that follow the repo's existing conventions.",
    "tools": ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
    "model": "sonnet"
  }
}

When a step attaches subagents, its log shows Subagents: test-writer, ….

Validation

The pipeline can’t be saved when:

• a name isn’t lowercase letters, digits or - (starting with a letter): Subagent "x": name must be lowercase letters, numbers or -
• two subagents share a name: Duplicate subagent "x"
• When to use or System prompt is empty
• a step references a subagent that doesn’t exist: Step "Name" uses unknown subagent "x"

Example

A pipeline whose implementer can hand off test writing and a security pass:

"subagents": [
  {
    "id": "test-writer",
    "description": "Writes focused unit tests for new or changed code. Use after implementing a change.",
    "prompt": "You write minimal, meaningful unit tests that follow the repository's existing test conventions. Run them and fix failures in the tests you wrote.",
    "tools": ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
    "model": "sonnet"
  },
  {
    "id": "security-check",
    "description": "Reviews a diff for security problems (injection, authz, secrets). Use before finishing any change that touches input handling or auth.",
    "prompt": "You are a security reviewer for {{issue.key}}. Inspect `git diff {{run.baseBranch}}...HEAD` and report concrete, exploitable problems with file:line references. Do not modify files.",
    "tools": ["Read", "Grep", "Glob", "Bash"]
  }
]

Attach both to the implement step and mention them in its prompt (“Use the test-writer subagent for tests and run security-check before you finish”) to make delegation more likely.

Tips

• Add subagents only when a step clearly benefits: a focused, tool-restricted helper keeps the main agent’s context small. For independent work that doesn’t need the main agent’s judgement, a separate parallel step is simpler and shows up in the graph.
• Restrict tools for reviewers (Read, Grep, Glob) so they can’t edit files.
• Subagents run inside the step, so their cost and tokens count toward that step (as reported by the harness).