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/"])What this subagent does. The main agent uses this to decide when to delegate.
Human-in-the-loop configuration for specific tools. Requires a checkpointer.
Additional middleware to append after default_middleware
The model for the agent. Defaults to defaultModel
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 the backend is a
CompositeBackend 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.
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.
System prompt override. Set to null to disable. Defaults to ASYNC_TASK_SYSTEM_PROMPT.
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/"],
};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/"],
};