DeepAgents CLI: Do subagents have to be defined in Python, or can they be defined via YAML?

OSS Product Help Deep Agents
1

Hi ,

In DeepAgents CLI, do custom subagents have to be defined in Python (as dict/object configs passed via subagents), and any YAML files I’ve seen are just descriptive configuration sources?

In other words, is YAML not a first-class, auto-loaded subagent definition format in DeepAgents CLI, but merely a way to describe subagent behavior that still needs to be converted into Python at runtime?

I use the following way to create a subagent.

image
image737×845 68.4 KB

/usr2/xxx/.deepagents/agent/.deepagents-subagents.yaml
But It seems deepagents-cli can’t create this subagent.

Thanks!

2

By the way, claude code can use subagent json to create a subagent. And user can change it’s setting.
Is it same for deepagents-cli by using yaml file?

3

Hello @Lee2026 Welcome to Langchain Community,

The path and format you’re using won’t work with DeepAgents CLI. It doesn’t support a flat .deepagents-subagents.yaml file at all, the subagent format is Markdown with YAML frontmatter, and the directory structure is specific.

To answer your core questions:

  • Yes, YAML is used, but only as frontmatter inside a Markdown file,. not as a standalone .yaml config file.
  • Yes, it’s first-class and auto-loaded, no Python code required. The CLI discovers and loads subagents automatically at startup.
  • No, it’s not the same as Claude Code’s JSON approach. The concept is similar, but DeepAgents uses AGENTS.md files in subfolders.

Here’s the correct setup:

Create this directory structure:

~/.deepagents/agent/agents/
└── my-researcher/
    └── AGENTS.md

And your AGENTS.md should look like:

---
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

Two things to fix from your attempt:

  1. Wrong path — you used ~/.deepagents/agent/.deepagents-subagents.yaml. The correct path is ~/.deepagents/agent/agents/{subagent-name}/AGENTS.md (note the agents/ subdirectory and the named subfolder).
  2. Wrong format — a standalone .yaml file is not recognized. You need an AGENTS.md file with YAML frontmatter (the --- delimited block at the top).

Required frontmatter fields:

  • name — unique identifier used to invoke the subagent
  • description — how the main agent decides when to delegate to it

Optional:

  • model — override the model for this subagent (e.g., anthropic:claude-haiku-4-5-20251001)

The body of the Markdown file (below the closing ---) becomes the subagent’s system prompt.

You can also define project-scoped subagents (available only within a specific project) by placing them at {project_root}/.deepagents/agents/{subagent-name}/AGENTS.md. Project subagents take precedence over user-level ones with the same name.