Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

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