Specification for a subagent that can be dynamically created.
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.
Always fully isolated — this subagent only ever sees the task description, never the parent's conversation. Use ForkedSubAgent to inherit the parent's history and system prompt instead.
interface SubAgentSubAgentBaseconst researcher: SubAgent = {
name: "researcher",
description: "Research assistant for complex topics",
systemPrompt: "You are a research assistant.",
tools: [webSearchTool],
skills: ["/skills/research/"],
};Description shown to the model for subagent selection
Additional middleware to append after default_middleware
Context mode. "handoff" (default) is fully isolated. "fork" inherits
the parent's conversation history and system prompt.
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.
// Parent denies /restricted/**; this subagent can read it.
const reader: SubAgent = {
name: "reader",
permissions: [
{ operations: ["read"], paths: ["/restricted/**"] },
],
};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.
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(),
}),
};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.
const researcher: SubAgent = {
name: "researcher",
description: "Research assistant",
systemPrompt: "You are a researcher.",
skills: ["/skills/research/", "/skills/web-search/"],
};The system prompt to use for the agent
The tools to use for the agent (tool instances, not names). Defaults to defaultTools