# 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. Omit `model` to inherit the parent's model.

The parent model reads `description` to decide whether to delegate, so write it the way you write a [skill description](/docs/reference/skills.md#skills-instructions-and-tools).

The parent delegates through the `task` tool. A parent that limits its [built-in tools](/docs/reference/agent-config.md#harness-tools) must list `"task"`.

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

Subagents inherit the parent's execution surface. Discovery warns about
and ignores these directories inside a subagent: `tools/`, `skills/`,
`extensions/`, `mcp-connections/`, `host-connections/`, `channels/`,
`schedules/`, `reminders/`, `hooks/`, `sandbox/`, and nested
`subagents/`.

The parent's [instructions](/docs/reference/instructions.md) should say when to
delegate, such as "When a request needs background research, delegate
to the `researcher` subagent."

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