| Name | Type |
|---|---|
| name | str |
| description | str |
| system_prompt | str |
| tools | NotRequired[Sequence[BaseTool | Callable | dict[str, Any]]] |
| model | NotRequired[str | BaseChatModel] |
| middleware | NotRequired[list[AgentMiddleware]] |
| interrupt_on | NotRequired[dict[str, bool | InterruptOnConfig]] |
| skills | NotRequired[list[str]] |
| permissions | NotRequired[list[FilesystemPermission]] |
| response_format | NotRequired[ResponseFormat[Any] | type | dict[str, Any]] |
Specification for an agent.
When using create_deep_agent, subagents automatically receive a default middleware
stack (TodoListMiddleware, FilesystemMiddleware, SummarizationMiddleware, etc.) before
any custom middleware specified in this spec.
Required fields:
name: Unique identifier for the subagent.
The main agent uses this name when calling the `task()` tool.
description: What this subagent does.
Be specific and action-oriented. The main agent uses this to decide when to delegate.
system_prompt: Instructions for the subagent.
Include tool usage guidance and output format requirements.
Optional fields:
tools: Tools the subagent can use.
If not specified, inherits tools from the main agent via `default_tools`.
model: Override the main agent's model.
Use the format `'provider:model-name'` (e.g., `'openai:gpt-4o'`).
middleware: Additional middleware for custom behavior, logging, or rate limiting. interrupt_on: Configure human-in-the-loop for specific tools.
Requires a checkpointer.
skills: Skill source paths for SkillsMiddleware.
List of paths to skill directories (e.g., `["/skills/user/", "/skills/project/"]`).
permissions: Filesystem permission rules for this subagent.
If omitted, inherits the parent agent's permissions. If provided,
replaces the parent agent's rules entirely for this subagent.
Rules are evaluated in declaration order; the first match wins.