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.

The parent delegates through the task tool. A parent that limits its built-in tools must list "task".

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