Subagents
A subagent is a specialist child agent the model can delegate to
mid-turn. Each one lives under bot/subagents/<id>/ with a required
agent.ts. Add instructions.md or inline instructions in agent.ts
for a custom prompt. The parent model delegates through the task tool,
and the stream records subagent.called and subagent.completed.
subagent.completed has isError: true when the subagent failed or was
cancelled.
bot/subagents/researcher/├── agent.ts # description (required), model (optional)└── instructions.md # optional custom system prompt// bot/subagents/researcher/agent.tsimport { defineAgent } from "@cursor/bdk";export default defineAgent({ description: "Background research: climate history, records, comparisons across many cities.", // model: omit to inherit the parent's model});Subagent rules
description is required. The parent model uses it to decide whether
to delegate, so write it as a routing rule ("Background research: …"),
following the same discipline as a skill description.
model is optional; omit it to inherit the parent's model, or set it
to run the specialist on a different model.
Subagents inherit the parent's execution surface. Every per-subagent
capability directory is reported as a warning and ignored: tools/,
skills/, extensions/, mcp-connections/, host-connections/,
channels/, schedules/, reminders/, hooks/, sandbox/, and
nested subagents/.
Delegation needs both halves: the description makes it possible, and the
parent's instructions make it happen. "When a
request needs background research, delegate to the researcher
subagent." The parent routes; the specialist executes.
Subagents and peers
Subagents split one job into roles inside a single agent. When the specialist is independently useful, with its own tools, sessions, and playground, make it a full agent. See Peer agents.
Related
- Skills: when a procedure is enough and a child agent is overkill
- Peer agents: independently useful specialists
- Agent config:
"task"on the parent's tool allowlist