Skip to main content
A running agent can delegate sub-tasks to your own named agents in .praisonai/agents/*.md — by name, mid-run, with no Python. 
# .praisonai/agents/researcher.md carries `mode: subagent`
praisonai run --agent lead "Draft a market brief on WebAssembly adoption"

<!-- .praisonai/agents/lead.md -->
---
model: gpt-4o
role: Team Lead
goal: Coordinate research and review, then write the final brief
---
You lead a small team. Delegate research and review to your teammates, then synthesise the result.

<!-- .praisonai/agents/researcher.md -->
---
model: gpt-4o-mini
role: Research Specialist
goal: Gather accurate, cited facts on a topic
mode: subagent
tools:
  - web_search
---
You are a meticulous researcher. Provide concise, cited findings.

<!-- .praisonai/agents/reviewer.md -->
---
model: gpt-4o
role: Editorial Reviewer
goal: Check drafts for accuracy and clarity
mode: subagent
---
You review drafts for accuracy, tone, and clarity. Suggest concrete edits.
Prefer to opt agents in per run instead of editing frontmatter? Use the --subagents allow-list: 
praisonai run --agent lead --subagents researcher,reviewer "Draft and review a market brief on X"

​
Quick Start

1

Mark an agent as delegatable

Add mode: subagent to any agent’s frontmatter. The agent’s author opts it in once, and every run can delegate to it.
<!-- .praisonai/agents/researcher.md -->
---
model: gpt-4o-mini
role: Research Specialist
mode: subagent
---
You are a meticulous researcher.
2

Or opt agents in from the CLI

Pass --subagents to expose exact agents for a single run, no frontmatter changes required.
praisonai run --agent lead --subagents researcher,reviewer "Write a brief on X"
3

Run the primary agent

praisonai run --agent lead "Draft a market brief on WebAssembly adoption"
The lead agent calls spawn_subagent(agent_name="researcher"), the resolver loads researcher.md, and the researcher runs under its own model, tools, and permissions.

​
How It Works

The primary agent picks a teammate by name; a resolver instantiates that agent from its Markdown definition and runs the sub-task.

​
Two ways to opt agents in

Choose per-agent frontmatter for stable teammates, or the CLI flag for ad-hoc runs.
RouteSet whereScopeBest for
mode: subagentAgent frontmatterEvery runStable teammates you always want available
--subagents a,b,cCLI flagSingle runAd-hoc delegation without editing files
When --subagents is passed, those exact names are exposed regardless of mode. When it is omitted, every agent whose frontmatter has mode: subagent is exposed. If neither yields any agent, the spawn_subagent tool is not wired at all and the run is identical to before.

​
What the delegated agent inherits

Each named agent runs under its own model, tools, and permissions from its frontmatter. The primary agent does not override them.
Generic spawn_subagentNamed agent delegation
Parent chooses the model, tools, and permission mode per callEach named agent brings its own model, tools, and permissions
Spawns a generic workerRuns your pre-defined .praisonai/agents/*.md agent
A named agent’s mode: subagent marker never changes its permissions — it only marks the agent as delegatable (see Delegatability vs permissions).

​
How the model discovers them

The tool description lists each delegatable agent so the primary model can pick one by purpose: 
You can delegate to these named agents by passing their name as agent_name
(each runs under its own model/tools/permissions):
- researcher: Gather accurate, cited facts on a topic
- reviewer: Check drafts for accuracy and clarity
Each line’s text is the agent’s description, falling back to goal, then role, then an empty string when none is set. Give every delegatable agent a clear goal or description so the primary model chooses the right teammate.

​
Fallback behaviour

Delegation is purely additive — nothing changes when there is nothing to delegate to.
  • Unknown name: if agent_name targets a name the resolver cannot find, the resolver returns None and the existing generic-spawn path runs instead.
  • No delegatable agents: if no agent is marked mode: subagent and --subagents is omitted, the spawn_subagent tool is not wired at all — the run is byte-identical to before.

​
Delegatability vs permissions

mode: subagent is a delegatability marker, not a permission mode. It is ignored (case-insensitive) when computing permissions, so it is never rejected as an unknown mode. Any other mode value — read-only, plan, accept-edits — still flows through the permission engine as before. See Custom Agents & Commands for the full mode reference.

​
Configuration Options

OptionTypeDefaultDescription
agent_resolverCallable[[str], Agent]NoneSDK callback that returns a ready-to-run Agent for a name. When a passed agent_name resolves, that named agent runs the sub-task under its own model/tools/permissions. None preserves generic-spawn behaviour.
resolvable_agentsDict[str, str]NoneSDK {name: description} map of delegatable agents; each entry enriches the tool description so the model can pick one.
--subagentsCLI flag—Comma-separated named agents (.praisonai/agents/*.md) the running agent may delegate to. Omit to expose agents marked mode: subagent.
agent_resolver and resolvable_agents are SDK parameters on create_subagent_tool. The CLI wires them for you from your .praisonai/agents/ definitions — you only need mode: subagent or --subagents.

​
Common Patterns

A lead delegates to two teammates marked mode: subagent:
praisonai run --agent lead "Draft and review a launch brief for our new API"
The lead calls spawn_subagent(agent_name="researcher") and spawn_subagent(agent_name="reviewer"), each running under its own frontmatter.

​
Best Practices

Mark agents you always want available with mode: subagent and commit them to git. Reach for --subagents when you need a one-off delegation without editing files.
The primary model picks teammates by their description (falling back to goal, then role). A vague goal makes the model guess; a specific one routes the right sub-task to the right agent.
Each named agent runs under its own permissions. Add a permission: block (or a mode: like read-only) to a delegated agent to sandbox its side-effects independently of the primary agent.
A delegated agent chatting to finish its sub-task is fine. Nested delegation — a delegated agent delegating again — is not part of this feature; design flat teams with a single coordinating agent.

Subagent Tool

The create_subagent_tool seam and its parameters

Subagent Delegation

Programmatic spawn control and parallel fan-out

Custom Agents & Commands

Define named agents in .praisonai/agents/*.md

Handoffs

Agent-to-agent routing inside a conversation