Agent SDK

Appearance

Subagents ​

A subagent is a specialist child agent the model can delegate to mid-turn. Each one is its own directory under agent/subagents/<id>/, with the same agent.ts + instructions.md shape as the root. On the Cursor harness, subagents run as SDK custom subagents: the parent model delegates through the harness task tool, and the stream records subagent.called and subagent.completed.

text
agent/subagents/researcher/
├── agent.ts            # description (required), model (optional)
└── instructions.md     # the subagent's own system prompt
ts
// agent/subagents/researcher/agent.ts
import { defineAgent } from "@cursor/july";

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. It's the only thing the parent model reads when deciding whether to delegate, so write it as a routing rule ("Background research: …"), 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 one.

Subagents inherit the parent's execution surface. Every per-subagent capability directory is reported as a warning and ignored: tools/, skills/, mcp-connections/ (and the legacy connections/ alias), channels/, schedules/, 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."

Subagent or peer? ​

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 and wire a peer MCP connection instead. The comparison table is in the Agent-to-agent guide.

Patterns ​

Fan-out reviews: a PR-approval agent can delegate to two review subagents that read a host-prepared pr/ evidence tree and report prioritized findings, which the parent embeds in its approval comment.

Keep the parent lean: a subagent with focused instructions usually works better than a longer parent prompt with conditional sections. The parent routes; the specialist executes.

What's next ​

Continue with these pages:

  • Agent-to-agent: the peer alternative
  • Skills: when a procedure is enough and a child agent is overkill