CLI Subagent Delegation

Let one praisonai run delegate mid-flight to your other named agents

Turn .praisonai/agents/*.md files into composable delegation targets your running agent can hand sub-tasks to, all from the CLI.

This is CLI-first delegation of named user agents — distinct from the SDK-level Subagent Tool and Subagent Delegation. No Python required: define agents as one-file Markdown definitions and expose them with a single flag.

Quick Start

1. Create two named agents

   Add agent definitions under .praisonai/agents/. Each file’s name is the agent name.

   ---
   role: Researcher
   goal: Gather facts and sources on a topic
   mode: subagent
   ---
   You research topics thoroughly and return concise, sourced findings.

   ---
   role: Summariser
   goal: Condense findings into a short brief
   mode: subagent
   ---
   You turn detailed notes into a clear one-paragraph summary.

2. Run with delegation enabled

   Pass the delegatable agents as a comma-separated allow-list.

   praisonai run "Research vector databases and give me a short brief" \
     --subagents researcher,summariser

3. See what the primary agent discovers

   The spawn_subagent tool description auto-lists your agents so the model knows who to delegate to:

   You can delegate to these named agents by passing their name as agent_name
   (each runs under its own model/tools/permissions):
   - researcher: Gather facts and sources on a topic
   - summariser: Condense findings into a short brief

How It Works

The primary agent calls spawn_subagent(agent_name="researcher", ...); a resolver builds that named agent from its Markdown definition and runs the sub-task under its own model, tools, and permissions.

Two Ways to Opt In

Expose agents either explicitly from the CLI or by marking the definition file.

• --subagents researcher,summariser — an explicit allow-list that wins over any marker. Opt any named agent in without editing it.
• mode: subagent — a frontmatter marker exposing that agent whenever no allow-list is passed.

Fallback Behaviour

When the model targets a name that isn’t a delegatable agent, the tool uses the generic spawn path instead of failing.

praisonai run "Explore the auth module" --subagents researcher

If the model calls spawn_subagent(agent_name="explorer") and explorer isn’t in the allow-list, a generic subagent handles the task — see Subagent Tool. Delegation to named agents is fully backward-compatible: with no --subagents and no mode: subagent markers, runs behave exactly as before.

Common Patterns

Compose named agents into small pipelines from the CLI.

# Research pipeline: one agent gathers, another condenses
praisonai run "Brief me on RAG evaluation" --subagents researcher,summariser

# Writer + reviewer pair
praisonai run "Draft and review the release notes" --subagents writer,reviewer

# Specialised domain agents
praisonai run "Audit the payment flow" --subagents security,coder

Best Practices

Related