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.

1 Like
5

Hi @keenborder786

Thanks for replying.
Another question：
Can subagent which created by yaml file use user-defined tools？
For example, I create a user-defined tool which name is analyze-log.
And can this subagent use this tool?

6

Not directly through the AGENTS.md file, but the subagent automatically inherits the main agent’s tools.
There is no tools field in the AGENTS.md format. You cannot selectively assign or restrict tools to a file-based subagent.
So your analyze-log tool, if it’s registered with the main agent, is automatically available to the subagent too.