Agent SDK0.2.29

Appearance

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

  • 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