Specification for a declarative subagent.
When using createDeepAgent, subagents automatically receive a default middleware
stack (filesystemMiddleware, summarizationMiddleware, etc.) before any custom
middleware specified in this spec. Add todoListMiddleware explicitly to opt in.
By default the subagent is isolated — it only ever sees the delegated task
description, never the parent's conversation. Setting mode: "fork" makes
it continue the parent's conversation instead.
Description shown to the model for subagent selection
Human-in-the-loop configuration for specific tools. Requires a checkpointer.
Additional middleware to append after default_middleware
Context mode. "isolated" (default) only sees the delegated task.
"fork" inherits the parent's conversation history and mirrors the
parent's prompt-producing middleware (skills, memory, custom middleware)
so it rebuilds an equivalent system prompt — the tradeoff is cache
misses if this subagent's own model differs from the parent's. Cannot
declare skills under mode: "fork"; the parent's skills are inherited
instead.
The model for the agent. Defaults to defaultModel
Identifier used to select this subagent in the task tool
Filesystem permission rules for this subagent.
When specified, these rules replace the parent agent's permissions for all tool calls made by this subagent. When omitted, the subagent inherits the parent agent's permissions.
Subagent permissions are a full replacement, not a merge.
Structured output response format for the subagent.
When specified, the subagent will produce a structuredResponse conforming to the
given schema. The structured response is JSON-serialized and returned as the
ToolMessage content to the parent agent, replacing the default last-message extraction.
Accepts any format supported by createAgent: Zod schemas, JSON schema objects,
toolStrategy(schema), providerStrategy(schema), etc.
Skill source paths for SkillsMiddleware.
List of paths to skill directories (e.g., ["/skills/user/", "/skills/project/"]).
When specified, the subagent will have its own SkillsMiddleware that loads skills
from these paths. This allows subagents to have different skill sets than the main agent.
Note: Custom subagents do NOT inherit skills from the main agent by default. Only the general-purpose subagent inherits the main agent's skills.
The system prompt for the agent. Falls back to an empty prompt if
omitted. Under mode: "fork", this is appended to the parent's
inherited prompt rather than replacing it.
The tools to use for the agent (tool instances, not names). Defaults to defaultTools
const researcher: SubAgent = {
name: "researcher",
description: "Research assistant for complex topics",
systemPrompt: "You are a research assistant.",
tools: [webSearchTool],
skills: ["/skills/research/"],
};// Parent denies /restricted/**; this subagent can read it.
const reader: SubAgent = {
name: "reader",
permissions: [
{ operations: ["read"], paths: ["/restricted/**"] },
],
};import { z } from "zod"
const analyzer: SubAgent = {
name: "analyzer",
description: "Analyzes data and returns structured findings",
systemPrompt: "Analyze the data and return your findings.",
responseFormat: z.object({
findings: z.string(),
confidence: z.number(),
}),
};const researcher: SubAgent = {
name: "researcher",
description: "Research assistant",
systemPrompt: "You are a researcher.",
skills: ["/skills/research/", "/skills/web-search/"],
};