Skip to main content
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

1

Define a named agent

Create .praisonai/agents/researcher.md:
---
name: researcher
mode: subagent
model: gpt-4o
tools:
  - web_search
---

You are a careful research subagent. Find primary sources and summarise them.
2

Delegate to it by name

Run any agent with the researcher subagent exposed:
praisonai run --agent writer --subagents researcher "Write a summary of the 2024 EU AI Act"
The writer agent can now call researcher mid-run. researcher runs under its own model and tools.
--subagents applies to a named agent run (--agent <name>). The running agent gains a spawn_subagent tool whose description lists the agents it may delegate to.

​
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.
StepWhat happens
Discover.praisonai/agents/*.md definitions are loaded
ExposeDelegatable agents are listed in the spawn_subagent tool description
ResolveA targeted name is instantiated as its own Agent
RunThe named agent runs under its own model, tools, and permissions
Fall backAn 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.
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"
mode: subagent is a marker, not a permission mode. It only makes a definition delegatable — it grants no permissions. Scope tools and permissions with model, tools, and the permission block.

​
Definition File Schema

Each .praisonai/agents/<name>.md file uses YAML frontmatter followed by the system prompt as the body.
KeyTypeDescription
namestringThe delegation name (defaults to the filename stem)
descriptionstringShown in the dynamic tool description so the primary agent knows when to pick this subagent
mode: subagentstringMarker that makes this definition delegatable (not a permission mode)
modelstringLLM the subagent runs under (maps to llm)
toolslistTool names available to the subagent
rolestringOptional role
goalstringOptional goal (used as the tool description when description is absent)
permissionmapOptional 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.
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"
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"
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

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.
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.
--subagents a,b opts agents in without editing files, and wins over mode: subagent markers. Use markers for agents you always want delegatable.
With no delegatable agents, nothing changes — the spawn_subagent tool is not wired. An unresolved name falls back to the existing generic spawn.

Subagent Delegation

Programmatic spawn control, scoped permissions, and parallel fan-out.

Background Subagents

Fire-and-forget subagents that return a job ID and deliver results later.