# 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.

```text
bot/subagents/researcher/
├── agent.ts            # description (required), model (optional)
└── instructions.md     # optional custom system prompt
```

```ts
// bot/subagents/researcher/agent.ts
import { defineAgent } from "@grok/agent-sdk";

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](/docs/reference/skills.md) 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](/docs/reference/instructions.md) 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](/docs/guides/agent-to-agent.md#peer-or-subagent).

## Related

- [Skills](/docs/reference/skills.md): when a procedure is enough and a child agent
  is overkill
- [Peer agents](/docs/guides/agent-to-agent.md): independently useful
  specialists
- [Agent config](/docs/reference/agent-config.md#harness-tools): `"task"` on the
  parent's tool allowlist