Named Subagents
Delegate to your own named agents mid-run — one Markdown file each, no Python
A running agent can delegate a sub-task to one of your own named agents by name, and that agent runs under its own model, tools, and permissions.
Define an agent in .praisonai/agents/researcher.md, then let any run delegate to it — no Python file required.
Quick Start
- Define a named agent
Create
.praisonai/agents/researcher.md:markdown --- name: researcher mode: subagent model: gpt-4o tools: - web_search --- You are a careful research subagent. Find primary sources and summarise them. - Delegate to it by name
Run any agent with the
researchersubagent exposed:bash praisonai run --agent writer --subagents researcher "Write a summary of the 2024 EU AI Act"The
writeragent can now callresearchermid-run.researcherruns under its own model and tools.
How It Works
The wrapper discovers .praisonai/agents/*.md, builds a resolver, and hands it to the core subagent tool. When the model targets a named agent that resolves, that agent runs the sub-task under its own definition.
| Step | What happens |
|---|---|
| Discover | .praisonai/agents/*.md definitions are loaded |
| Expose | Delegatable agents are listed in the spawn_subagent tool description |
| Resolve | A targeted name is instantiated as its own Agent |
| Run | The named agent runs under its own model, tools, and permissions |
| Fall back | An unresolved name uses the existing generic spawn |
Two Ways to Opt In
Choose which named agents a run may delegate to with either a CLI allow-list or a frontmatter marker.
Allow-list (CLI flag)
Expose specific agents for this run. The flag takes precedence over any markers:
praisonai run --agent writer --subagents researcher,reviewer "Draft and review the RFC"Frontmatter marker
Mark a definition delegatable so it is exposed whenever no --subagents flag is given:
---
name: researcher
mode: subagent
model: gpt-4o
tools:
- web_search
---
You are a careful research subagent…praisonai run --agent writer "Draft the RFC using the researcher when you need sources"Definition File Schema
Each .praisonai/agents/<name>.md file uses YAML frontmatter followed by the system prompt as the body.
| Key | Type | Description |
|---|---|---|
name | string | The delegation name (defaults to the filename stem) |
description | string | Shown in the dynamic tool description so the primary agent knows when to pick this subagent |
mode: subagent | string | Marker that makes this definition delegatable (not a permission mode) |
model | string | LLM the subagent runs under (maps to llm) |
tools | list | Tool names available to the subagent |
role | string | Optional role |
goal | string | Optional goal (used as the tool description when description is absent) |
permission | map | Optional per-capability permission rules (e.g. bash: {"*": deny}) |
The Markdown body (after the frontmatter) becomes the agent’s instructions.
Common Patterns
Compose named agents into CLI-first workflows with no Python.
Research → write pipeline
Two named agents, each in its own file:
---
name: researcher
mode: subagent
model: gpt-4o
tools:
- web_search
---
Find primary sources and summarise them.---
name: writer
mode: subagent
model: gpt-4o
---
Write clear, well-structured prose from provided research.praisonai run --agent writer --subagents researcher "Write a briefing on quantum error correction"Selective reviewer
Expose a reviewer the primary agent invokes only when it needs a second pass:
---
name: reviewer
description: Audits drafts for accuracy and tone; read-only
mode: subagent
permission:
edit: deny
write: deny
---
You are a meticulous reviewer. Do not modify files.praisonai run --agent writer --subagents reviewer "Draft the release notes, then have the reviewer check them"CLI-first multi-agent — no Python
A whole multi-agent workflow lives in Markdown files under .praisonai/agents/:
praisonai run --agent planner --subagents researcher,writer,reviewer "Plan, research, write, and review the report"Best Practices
Give each agent a clear description
The description (or goal) appears in the tool description the primary agent sees, so a specific one-liner helps it pick the right subagent for each sub-task.
Scope tools per agent, not per caller
A resolved named agent runs under its own model, tools, and permission — never the caller’s. Keep each definition’s tools minimal for its job.
Use the allow-list for one-off runs
--subagents a,b opts agents in without editing files, and wins over mode: subagent markers. Use markers for agents you always want delegatable.
Backward compatible by default
With no delegatable agents, nothing changes — the spawn_subagent tool is not wired. An unresolved name falls back to the existing generic spawn.