Specification for a subagent that can be dynamically created.
When using createDeepAgent, subagents automatically receive a default middleware
stack (todoListMiddleware, filesystemMiddleware, summarizationMiddleware, etc.) before
any custom middleware specified in this spec.
Required fields:
name: Identifier used to select this subagent in the task tooldescription: Shown to the model for subagent selectionsystemPrompt: The system prompt for the subagentOptional fields:
model: Override the default model for this subagenttools: Override the default tools for this subagentmiddleware: Additional middleware appended after defaultsinterruptOn: Human-in-the-loop configuration for specific toolsskills: Skill source paths for SkillsMiddleware (e.g., ["/skills/user/", "/skills/project/"])interface SubAgentconst researcher: SubAgent = {
name: "researcher",
description: "Research assistant for complex topics",
systemPrompt: "You are a research assistant.",
tools: [webSearchTool],
skills: ["/skills/research/"],
};What this subagent does. The main agent uses this to decide when to delegate.
Additional middleware to append after default_middleware
The model for the agent. Defaults to defaultModel
Error name for instanceof checks and logging
Filesystem permission rules enforced on every tool call.
Rules are evaluated in declaration order; first match wins; permissive
default. Applies to ls, read_file, write_file, edit_file,
glob, and grep.
Note on execute: permissions are not enforced on execute because
shell commands can access any path regardless of path-based rules. Using
permissions with an execution-capable backend (one where isSandboxBackend
returns true) throws a ConfigurationError unless either:
execute is disabled via tools, orCompositeBackend and every permission path is scoped to
a route prefix.When omitted or empty, all filesystem operations are permitted.
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/"],
};System prompt override. Set to null to disable. Defaults to ASYNC_TASK_SYSTEM_PROMPT.
Allowlist of built-in filesystem tools to expose to the model.
undefined, null, and "all" preserve the default behavior: every
filesystem tool is registered, subject to backend capability filtering.read_file must be included in every explicit array because it is used
by normal file-inspection flows and by large-result recovery guidance.execute is removed when the resolved backend does not support
command execution, even if it appears in this allowlist.The generated filesystem system prompt is based on the tools that remain visible after this allowlist and backend capability filtering are applied.
createFilesystemMiddleware({
tools: ["read_file", "ls", "glob", "grep"],
});