Use subagents in Deep Agents Code

Define custom synchronous subagents as markdown files so Deep Agents Code can delegate specialized tasks to them.

Async subagents are not available to end-users in Deep Agents Code at this time.

Each subagent lives in its own folder with an AGENTS.md file:

.deepagents/agents/{subagent-name}/AGENTS.md   # Project-level
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md  # User-level

Project subagents override user subagents with the same name (see precedence rules). The frontmatter requires name and description (same as the SubAgent dictionary spec). The markdown body becomes the subagent’s system_prompt. In addition to the base spec, AGENTS.md files support an optional model frontmatter field that overrides the main agent’s model for this subagent. Use the provider:model-name format (e.g., anthropic:claude-opus-4-8, openai:gpt-5.5). Omit it to inherit the main agent’s model.

Other SubAgent fields (tools, middleware, interrupt_on, skills) are currently not configurable via AGENTS.md frontmatter—custom subagents defined this way inherit the main agent’s tools. Use the SDK directly for full control.

File format

Subagent AGENTS.md files use YAML frontmatter followed by a markdown body:

---
name: researcher
description: Research topics on the web before writing content
model: anthropic:claude-haiku-4-5-20251001
---

You are a research assistant with access to web search.

## Your Process
1. Search for relevant information
2. Summarize findings clearly

Example: cost-efficient subagents

Use a cheaper, faster model for simple delegation tasks while keeping the main agent on a more capable model:

---
name: general-purpose
description: General-purpose agent for research and multi-step tasks
model: anthropic:claude-haiku-4-5-20251001
---

You are a general-purpose assistant. Complete the task efficiently and return a concise summary.

This overrides the built-in general-purpose subagent, routing all delegated tasks to a cheaper model. See Override the general-purpose subagent for more.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​File format

​Example: cost-efficient subagents

File format

Example: cost-efficient subagents