Skip to main content
The Subagent Tool enables agents to spawn specialized subagents for specific tasks, with full control over model selection and permission modes.

​
Quick Start

1

Create Subagent Tool

from praisonaiagents.tools.subagent_tool import create_subagent_tool

tool = create_subagent_tool()
2

Spawn a Subagent

func = tool["function"]
result = func(task="Analyze the authentication module")

if result["success"]:
    print(result["output"])
3

With Model and Permission Mode

tool = create_subagent_tool(
    default_llm="gpt-4o-mini",
    default_permission_mode="plan"
)

func = tool["function"]
result = func(
    task="Explore the codebase",
    llm="gpt-4o",  # Override model
    permission_mode="plan"  # Read-only mode
)

​
Configuration Options

from praisonaiagents.tools.subagent_tool import create_subagent_tool

tool = create_subagent_tool(
    agent_factory=my_factory,      # Custom agent factory
    allowed_agents=["explorer"],   # Restrict agent types
    max_depth=3,                   # Maximum nesting depth
    default_llm="gpt-4o-mini",     # Default LLM model
    default_permission_mode="plan" # Default permission mode
)
ParameterTypeDefaultDescription
agent_factoryCallableNoneCustom function to create agents
allowed_agentsList[str]NoneRestrict which agent types can be spawned
max_depthint3Maximum subagent nesting depth
default_llmstrNoneDefault LLM model for subagents
default_permission_modestrNoneDefault permission mode

​
Spawn Parameters

When calling the subagent function: 
func = tool["function"]
result = func(
    task="Your task description",
    agent_name="explorer",
    context="Additional context",
    tools=["read_file", "search"],
    llm="gpt-4o",
    permission_mode="plan"
)
ParameterTypeRequiredDescription
taskstr✅ YesTask description for the subagent
agent_namestrNoSpecific agent type to use
contextstrNoAdditional context for the task
toolsList[str]NoTools to give the subagent
llmstrNoLLM model override
permission_modestrNoPermission mode override

​
Model Selection

Model selection priority:
  1. Per-call llm parameter - Highest priority
  2. default_llm from tool creation - Fallback
  3. Agent’s default model - Final fallback
# Set default for all subagents
tool = create_subagent_tool(default_llm="gpt-4o-mini")

# Override for specific call
result = func(task="Complex analysis", llm="gpt-4o")

​
Permission Modes

ModeValueDescription
defaultStandardNormal permission checking
accept_editsAuto-acceptAuto-accept file edits
dont_askAuto-denyAuto-deny all prompts
bypass_permissionsBypassSkip all checks
planRead-onlyExploration mode only
# Read-only exploration
tool = create_subagent_tool(default_permission_mode="plan")

# Auto-accept for refactoring
result = func(
    task="Refactor the utils module",
    permission_mode="accept_edits"
)

​
Custom Agent Factory

Create agents with custom configurations: 
from praisonaiagents import Agent

def my_agent_factory(name, tools=None, llm=None):
    return Agent(
        name=name,
        instructions=f"You are a {name} agent",
        tools=tools or [],
        llm=llm or "gpt-4o-mini"
    )

tool = create_subagent_tool(
    agent_factory=my_agent_factory,
    default_llm="gpt-4o-mini"
)

​
Depth Limiting

Prevent infinite subagent recursion: 
# Limit to 2 levels of nesting
tool = create_subagent_tool(max_depth=2)

# First subagent can spawn another
# Second subagent cannot spawn more
The default max_depth=3 prevents runaway subagent spawning. Increase with caution.

​
Agent Restrictions

Limit which agent types can be spawned: 
tool = create_subagent_tool(
    allowed_agents=["explorer", "reviewer"]
)

# This works
result = func(task="Explore code", agent_name="explorer")

# This fails
result = func(task="Write code", agent_name="coder")
# Returns: {"success": False, "error": "Agent 'coder' not in allowed list"}

​
Result Structure

result = func(task="Analyze code")

# Success response
{
    "success": True,
    "output": "Analysis results...",
    "agent_name": "subagent",
    "task": "Analyze code",
    "llm": "gpt-4o-mini",
    "permission_mode": "plan"
}

# Error response
{
    "success": False,
    "error": "Error message",
    "output": None
}

​
Best Practices

Use smaller models like gpt-4o-mini for simple tasks and larger models for complex analysis.
Always set permission_mode="plan" for exploration tasks to prevent accidental modifications.
Restrict allowed_agents to only the agent types needed for your use case.
Always check result["success"] before accessing the output.

Subagent Delegation

Advanced subagent management

Permission Modes

Permission mode details