Subagent Delegation

Spawn and manage subagents with scoped permissions and concurrency control

Subagent delegation lets a parent agent spawn specialised workers with scoped permissions, timeouts, and parallel execution.

from praisonaiagents import Agent
from praisonaiagents.tools.subagent_tool import create_subagent_tool

coordinator = Agent(
    name="Coordinator",
    instructions="Delegate read-only exploration to subagents.",
    tools=[create_subagent_tool(
        default_permission_mode="plan",
        allowed_agents=["explorer"],
    )],
)

coordinator.start("Find where authentication is implemented")

The user asks the coordinator; delegated subagents explore with scoped permissions.

For delegating to your own named agents defined in .praisonai/agents/*.md — by name, mid-run, with no Python — see Named Agent Delegation.

For agent-to-agent routing inside a conversation, prefer Handoffs. Use the subagent tool or delegator when you need programmatic spawn control, background jobs, or parallel fan-out.

Quick Start

1. Subagent Tool on an Agent

   Attach create_subagent_tool so the parent can spawn workers:

   from praisonaiagents import Agent
   from praisonaiagents.tools.subagent_tool import create_subagent_tool
   
   agent = Agent(
       name="Lead",
       instructions="Delegate exploration tasks to subagents.",
       tools=[create_subagent_tool(default_permission_mode="plan")],
   )
   
   agent.start("Explore the auth module read-only")
   
2. Programmatic Delegator

   For direct async control, use SubagentDelegator:

   from praisonaiagents.agents.delegator import SubagentDelegator, DelegationConfig
   import asyncio
   
   delegator = SubagentDelegator(config=DelegationConfig(max_concurrent_subagents=3))
   
   async def run():
       result = await delegator.delegate(
           agent_name="explorer",
           objective="Find authentication-related files",
           context={"workspace": "/path/to/project"},
       )
       print(result.result if result.success else result.error)
   
   asyncio.run(run())
   

---

How It Works

Phase	What happens
1. Delegate	The parent spawns a subagent with a scoped permission mode
2. Execute	The subagent runs within its timeout and step limits
3. Aggregate	Results flow back to the parent for a final answer

---

Named Delegation from the CLI (--subagents)

A running agent can delegate sub-tasks to your own named agents in .praisonai/agents/*.md — by name, mid-run, with no Python. Each delegated agent runs the sub-task under its own model, tools, and permissions.

1. Create two named agents

   Add a description: in each file’s frontmatter so the model knows what the agent is for. .praisonai/agents/researcher.md:

   ---
   description: Researches a topic and gathers sources
   model: gpt-4o-mini
   ---
   You are a focused researcher. Gather accurate, sourced findings.
   

   .praisonai/agents/writer.md:

   ---
   description: Writes a concise summary from research notes
   model: gpt-4o
   ---
   You turn research notes into a clear, concise summary.
   
2. Allow-list them at run time

   praisonai run "Research X and write a summary" --subagents researcher,writer
   

   The main agent can now call spawn_subagent(agent_name="researcher", ...) and the resolver runs your researcher agent under its own definition.

Two ways to expose a named agent

Allow-list flag (--subagents)

Opt any discovered agent in from the CLI without editing it:

praisonai run "<task>" --subagents researcher,writer

The allow-list takes precedence over the frontmatter marker.

Frontmatter marker (mode: subagent)

Mark an agent as delegatable in its own file — no flag needed:

---
mode: subagent
description: Reviews a diff for security issues
---
You review diffs and report security concerns only.

mode: subagent is a marker only — it is not a permission mode and does not restrict the agent.

How resolution works

When the target name is unknown, the resolver returns nothing and the tool falls through to the existing generic-spawn behaviour — so a typo never breaks the run.

--subagents vs mode: subagent

Backward compatible. With no --subagents allow-list and no mode: subagent marker, no named resolver is wired and delegation behaves exactly as before — identical generic-spawn behaviour (agent_resolver=None).

--subagents applies when running a custom agent (for example praisonai run "<task>" --agent path/to/agent.md). Named agents are discovered from ~/.praisonai/agents/ and every .praisonai/agents/ up to the repo root.

---

Built-in Agent Profiles

Agent	Mode	Description
general	Primary	General-purpose coding assistant
coder	All	Focused code implementation
planner	Subagent	Task planning and decomposition
reviewer	Subagent	Code review and quality
explorer	Subagent	Read-only codebase investigation
debugger	Subagent	Debugging and troubleshooting

agents = delegator.get_available_agents()
desc = delegator.get_agent_description("explorer")

---

Parallel Delegation

results = await delegator.delegate_parallel([
    ("explorer", "Find authentication files"),
    ("explorer", "Find database models"),
    ("explorer", "Find API endpoints"),
])

With per-task context:

results = await delegator.delegate_parallel([
    ("explorer", "Find auth files", {"workspace": "/project"}),
    ("reviewer", "Review security", {"files": ["auth.py"]}),
])

---

Configuration Options

Option	Type	Default	Description
max_concurrent_subagents	int	3	Max subagents running at once
max_total_subagents	int	10	Max total spawned
default_timeout_seconds	float	300.0	Default task timeout
max_timeout_seconds	float	600.0	Maximum allowed timeout
max_steps_per_subagent	int	50	Max steps per subagent
max_tokens_per_subagent	int	50000	Max tokens per subagent
inherit_permissions	bool	True	Inherit from parent
allow_nested_delegation	bool	False	Allow subagents to delegate
auto_cancel_on_parent_cancel	bool	True	Cancel children when parent stops
collect_results	bool	True	Aggregate results

from praisonaiagents.agents.delegator import DelegationConfig

config = DelegationConfig(
    max_concurrent_subagents=3,
    max_total_subagents=10,
    default_timeout_seconds=300.0,
    allow_nested_delegation=False,
)

---

Model and Permission Modes

Mode	Description
default	Standard permission checking
accept_edits	Auto-accept file edits
dont_ask	Auto-deny prompts
bypass_permissions	Skip all checks (dangerous)
plan	Read-only exploration mode

See Subagent Tool for create_subagent_tool parameters and background mode.

---

Task Management

# Cancel specific task or all running tasks
await delegator.cancel_task(task_id)
await delegator.cancel_all()

# Status and stats
status = delegator.get_task_status(task_id)
running = delegator.get_running_tasks()
stats = delegator.get_stats()

---

Convenience Function

from praisonaiagents.agents.delegator import delegate_to_agent

result = await delegate_to_agent(
    agent_name="explorer",
    objective="Find all Python files",
    context={"workspace": "/project"},
    timeout_seconds=60,
)

---

Best Practices

Match agent profiles to the task

Use explorer for read-only scans, coder for implementation, and reviewer for quality checks.

Set timeouts on long tasks

Prevent runaway subagents with default_timeout_seconds or per-call overrides.

Limit concurrency

Keep max_concurrent_subagents low to avoid overwhelming APIs or local resources.

Prefer plan mode for exploration

Use permission_mode="plan" when subagents should not modify files.

---

Delegating to Your Named Agents

Beyond the built-in profiles, a running agent can delegate to your own named agents in .praisonai/agents/*.md — picked by name, each running under its own model, tools, and permissions. Mark an agent with mode: subagent or opt agents in per run with praisonai run --subagents a,b,c.

praisonai run --agent lead --subagents researcher,reviewer "Draft and review a brief on X"

The dedicated Named Agent Delegation page owns this topic in full.

Related

Named Subagents

Delegate to your own named agents by name — one Markdown file each

Subagent Tool

Spawn subagents from a parent agent’s tool list

Spawn & Announce

Non-blocking parallel sub-agent orchestration

Agent Profiles

Built-in profile definitions

Handoffs

Conversation-based agent routing