Subagent Tool

Spawn subagents dynamically with model and permission control

The Subagent Tool lets a parent agent spawn specialised subagents for specific tasks — synchronously, or in the background so the parent keeps working and collects the result later.

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

parent = Agent(
    name="Coordinator",
    instructions="Delegate exploration to subagents when needed.",
    tools=[create_subagent_tool(default_permission_mode="plan")],
)

parent.start("Explore the auth module read-only")

The user asks the coordinator; the parent spawns a subagent with the requested permissions.

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
)

Parameter	Type	Default	Description
agent_factory	Callable	None	Custom function to create agents
allowed_agents	List[str]	None	Restrict which agent types can be spawned
max_depth	int	3	Maximum subagent nesting depth
default_llm	str	None	Default LLM model for subagents
default_permission_mode	str	None	Default permission mode
agent_resolver	Callable[[str], Agent]	None	Callback (name) -> Agent — returns a pre-configured Agent for a name, or None to fall back to the generic factory. The resolved agent runs under its own model/tools/permissions. Backward compatible: None keeps the prior generic-spawn behaviour.
resolvable_agents	Dict[str, str]	None	{name: description} map of delegatable agents; each entry appears in the tool description so the model knows which named agents it may delegate to.

---

Delegating to Named Agents

Pass agent_resolver to let the parent delegate to your own named agents instead of spawning a generic worker. When a passed agent_name resolves, that named agent runs the sub-task under its own model, tools, and permissions.

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

def resolve(name):
    # Return a ready-to-run Agent for the given name, or None to fall back.
    if name == "researcher":
        return Agent(name="researcher", role="Research Specialist", llm="gpt-4o-mini")
    return None

tool = create_subagent_tool(
    agent_resolver=resolve,
    resolvable_agents={"researcher": "Gather accurate, cited facts on a topic"},
)

resolvable_agents enriches the tool description so the model knows which named agents it may delegate to. The CLI wires both parameters for you from .praisonai/agents/*.md — see Named Agent Delegation as the primary entry point.

---

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"
)

Parameter	Type	Required	Description
task	str	✅ Yes	Task description for the subagent
agent_name	str	No	Specific agent type to use
context	str	No	Additional context for the task
tools	List[str]	No	Tools to give the subagent
llm	str	No	LLM model override
permission_mode	str	No	Permission mode override
background	bool	No	When True, enqueue on the background job runner and return immediately with a job_id
deliver	str	No	Delivery target for a background job’s result — e.g. "origin", "all", or "telegram:12345". Only meaningful with background=True. Empty (default) keeps jobs pull-only.
platform	str	No	Origin platform (e.g. "telegram") — captured for deliver="origin". Usually supplied by the gateway context automatically.
chat_id	str	No	Origin chat/channel ID — captured for deliver="origin".
thread_id	str	No	Optional origin thread ID.
session_id	str	No	Optional origin session ID to preserve context.

---

Deliver Background Job Results Back to Chat

When a background job finishes, its result can be pushed back to the user’s chat automatically — no polling required.

from praisonaiagents.tools.subagent_tool import create_subagent_tool

tool = create_subagent_tool()
spawn = tool["function"]

handle = spawn(
    task="Run a full analysis of the repository",
    background=True,
    deliver="origin",
)

Delivery targets

Target	Behaviour
"" (empty, default)	Pull-only — use subagent_result(job_id) to collect
"origin"	Deliver to the chat that started the job (requires parent to have an origin)
"all"	Deliver to all channels registered on the gateway
"platform:chat_id"	Deliver to a specific platform/channel (e.g. "telegram:123456")
"platform:chat_id:thread_id"	Deliver to a specific thread

deliver="origin" requires the parent to have an origin context — inside a BotOS chat it does. From a plain script with no active chat context, the pull-only default (deliver="") applies. Failures are also delivered as a failure notice, so the user is never left waiting silently.

The deliver vocabulary mirrors the scheduling tool’s deliver= parameter. See JOB_COMPLETED Hook for the hook that fires on completion.

Backward compatibility: with no deliver target set, behaviour is byte-for-byte identical to before — pull-only via subagent_result.

---

Background Mode

Run a long subtask without blocking the parent agent. Use it for full test runs, broad codebase scans, or large refactors — anything where the parent agent should keep working instead of waiting.

1. Kick off in the background

   from praisonaiagents.tools.subagent_tool import create_subagent_tool
   
   tool = create_subagent_tool()
   spawn = tool["function"]
   
   handle = spawn(
       task="Run the full test suite",
       background=True,
   )
   job_id = handle["job_id"]
   
2. Keep working, then collect the result

   collect = tool["result_tool"]["function"]
   
   # Non-blocking poll — returns status="running" or status="completed"
   status = collect(job_id)
   
   # Or block until done
   final = collect(job_id, wait=True)
   if final["status"] == "completed":
       print(final["result"]["output"])
   
3. Handle failures cleanly

   result = collect(job_id, wait=True)
   
   if not result["success"]:
       print("Job failed:", result.get("error"))
   elif result["result"]["success"] is False:
       print("Subagent error:", result["result"]["error"])
   else:
       print(result["result"]["output"])
   

When to use background mode

Background return shapes

spawn_subagent(..., background=True) returns a handle (not a final result):

{
    "success": True,
    "job_id": "...",
    "status": "running",
    "agent_name": "subagent",
    "task": "...",
    "llm": "...",
    "permission_mode": "...",
}

subagent_result(job_id) polls without blocking:

# While running
{"success": True, "job_id": "...", "status": "running"}

subagent_result(job_id, wait=True) blocks until done:

# On completion — the subagent's normal result dict is under "result"
{
    "success": True,
    "job_id": "...",
    "status": "completed",
    "result": {"success": True, "output": "...", "agent_name": "...", ...},
}

# On failure
{"success": False, "job_id": "...", "status": "failed", "error": "..."}

# Unknown job_id
{"success": False, "job_id": "...", "error": "Job '...' not found"}

Depth (max_depth), allowed_agents, and per-call tools / llm / permission_mode apply to background subagents identically to synchronous ones. Background jobs run on a worker thread but inherit the same scoping the parent set up.

---

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

Mode	Value	Description
default	Standard	Normal permission checking
accept_edits	Auto-accept	Auto-accept file edits
dont_ask	Auto-deny	Auto-deny all prompts
bypass_permissions	Bypass	Skip all checks
plan	Read-only	Exploration 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"
)

Delegate to named agents

Turn discovered .praisonai/agents/*.md agents into delegation targets with a resolver. When the caller passes an agent_name that resolves, that named agent runs the sub-task under its own model / tools / permission.

from praisonai_code.cli.features.custom_definitions import build_subagent_resolver

resolver, descriptions = build_subagent_resolver()  # picks up mode: subagent agents
tool = create_subagent_tool(agent_resolver=resolver, resolvable_agents=descriptions)

See Named Agent Delegation for the full CLI-first story.

---

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

Synchronous calls (background=False, the default) return the final result directly:

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
}

Background calls return a handle — see Background Mode for subagent_result shapes.

When a call is served by an agent_resolver (named agent delegation), agent_name in the result is the resolved named agent (e.g. "researcher"), not "subagent". See Named Agent Delegation.

---

Best Practices

Use appropriate models

Use smaller models like gpt-4o-mini for simple tasks and larger models for complex analysis.

Set permission modes

Always set permission_mode="plan" for exploration tasks to prevent accidental modifications.

Limit allowed agents

Restrict allowed_agents to only the agent types needed for your use case.

Handle errors

Always check result["success"] before accessing the output.

Use background mode for long tasks

For test suites, broad scans, or refactors, use background=True so the parent agent can keep working and collect results with subagent_result.

---

Related

Named Agent Delegation

Delegate to your .praisonai/agents by name — no Python

Subagent Delegation

Advanced subagent management

Permission Modes

Permission mode details

JOB_COMPLETED Hook

Hook that fires when a background job finishes — success or failure