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.

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 Handoffs

   For direct async control, fan work out to focused agents with parallel_handoffs:

   from praisonaiagents import Agent, parallel_handoffs
   import asyncio
   
   lead = Agent(name="Lead", instructions="Coordinate exploration.")
   explorer = Agent(name="Explorer", instructions="Investigate the codebase read-only.")
   
   async def run():
       results = await parallel_handoffs(
           source=lead,
           targets=[
               (explorer, "Find authentication-related files"),
               (explorer, "Find database models"),
           ],
           max_concurrent=3,
       )
       for r in results:
           print(r.response if r.success else r.error)
   
   asyncio.run(run())

   For a single target, use lead.handoff_to_async(explorer, "Find auth files").

How It Works

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

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

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

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

Built-in Agent Profiles

from praisonaiagents.agents.profiles import list_profiles, get_profile

profiles = list_profiles()
explorer = get_profile("explorer")
print(explorer.description)

Parallel Delegation

Fan work out to multiple agents at once with parallel_handoffs — each (agent, prompt) tuple runs concurrently:

from praisonaiagents import Agent, parallel_handoffs

lead = Agent(name="Lead", instructions="Coordinate exploration.")
explorer = Agent(name="Explorer", instructions="Investigate the codebase.")

results = await parallel_handoffs(
    source=lead,
    targets=[
        (explorer, "Find authentication files"),
        (explorer, "Find database models"),
        (explorer, "Find API endpoints"),
    ],
    max_concurrent=3,
)

Route each prompt to a different specialist by passing different agents:

reviewer = Agent(name="Reviewer", instructions="Review security.")

results = await parallel_handoffs(
    source=lead,
    targets=[
        (explorer, "Find auth files"),
        (reviewer, "Review security of auth.py"),
    ],
)

Configuration Options

Parallel fan-out is tuned with HandoffConfig. The knobs you reach for most:

from praisonaiagents import parallel_handoffs, HandoffConfig

config = HandoffConfig(
    max_concurrent=3,
    timeout_seconds=300.0,
    allow_parallel=True,
)

results = await parallel_handoffs(source=lead, targets=targets, config=config)

Model and Permission Modes

See Subagent Tool for create_subagent_tool parameters and background mode.

Cancellation

A single async handoff is a coroutine — wrap it in your own asyncio.Task and .cancel() it to stop it early:

import asyncio
from praisonaiagents import Agent

lead = Agent(name="Lead", instructions="Coordinate work.")
explorer = Agent(name="Explorer", instructions="Investigate.")

task = asyncio.create_task(lead.handoff_to_async(explorer, "Scan the whole repo"))
# ...later, if it runs too long:
task.cancel()

For fan-out, parallel_handoffs bounds each target with timeout_seconds from HandoffConfig; cancel the outer task to stop the whole batch.

Best Practices

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