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

PhaseWhat happens
1. DelegateThe parent spawns a subagent with a scoped permission mode
2. ExecuteThe subagent runs within its timeout and step limits
3. AggregateResults flow back to the parent for a final answer

​
Built-in Agent Profiles

AgentModeDescription
generalPrimaryGeneral-purpose coding assistant
coderAllFocused code implementation
plannerSubagentTask planning and decomposition
reviewerSubagentCode review and quality
explorerSubagentRead-only codebase investigation
debuggerSubagentDebugging 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

OptionTypeDefaultDescription
max_concurrent_subagentsint3Max subagents running at once
max_total_subagentsint10Max total spawned
default_timeout_secondsfloat300.0Default task timeout
max_timeout_secondsfloat600.0Maximum allowed timeout
max_steps_per_subagentint50Max steps per subagent
max_tokens_per_subagentint50000Max tokens per subagent
inherit_permissionsboolTrueInherit from parent
allow_nested_delegationboolFalseAllow subagents to delegate
auto_cancel_on_parent_cancelboolTrueCancel children when parent stops
collect_resultsboolTrueAggregate 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

ModeDescription
defaultStandard permission checking
accept_editsAuto-accept file edits
dont_askAuto-deny prompts
bypass_permissionsSkip all checks (dangerous)
planRead-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

Use explorer for read-only scans, coder for implementation, and reviewer for quality checks.
Prevent runaway subagents with default_timeout_seconds or per-call overrides.
Keep max_concurrent_subagents low to avoid overwhelming APIs or local resources.
Use permission_mode="plan" when subagents should not modify files.

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