Subagents

When a task is too broad for a single reasoning thread, or when parts of it can be done in parallel, the Lead Agent delegates work to subagents. A subagent is a self-contained agent invocation that receives a specific task, executes it, and returns the result.

Why subagents matter

Subagents solve two key problems in long-horizon workflows:

1. Context isolation: a subagent only sees the information it needs for its piece of the task, not the entire parent conversation. This keeps each agent’s working context focused and tractable.
2. Parallelism: multiple subagents can run concurrently, allowing independent parts of a task (e.g., researching multiple topics simultaneously) to be processed in parallel.

Built-in subagents

PengBao AI ships with two built-in subagents:

general-purpose

A general-purpose reasoning and execution agent. Suitable for delegating complex subtasks that require multi-step reasoning, web search, file operations, and artifact production.

• Default timeout: 900 seconds (15 minutes)
• Default max turns: 160

bash

A subagent specialized for command-line task execution inside the sandbox. Suitable for scripting, data processing, file transformation, and environment setup tasks.

• Default timeout: 900 seconds (15 minutes)
• Default max turns: 80
• Availability: only exposed when the sandbox’s bash tool is available (either allow_host_bash: true or a container sandbox is configured)

Delegation flow

The Lead Agent delegates work to a subagent using the built-in task tool:

task(
  agent="general-purpose",
  task="Research the top 5 competitors of Acme Corp and summarize their pricing",
  context="Focus on B2B SaaS pricing models"
)

The runtime then:

1. Looks up the subagent configuration from the registry, applying any config.yaml overrides.
2. Creates a new agent invocation with the subagent’s own prompt and tools.
3. Runs the subagent to completion (or until timeout / max turns).
4. Returns the subagent’s final output to the Lead Agent as the tool result.

Configuration

Subagent timeouts and max turns are controlled through the subagents: section in config.yaml:

subagents:
  # Default timeout in seconds for all subagents (default: 900 = 15 minutes)
  timeout_seconds: 900
 
  # Optional: override max turns for all subagents
  # max_turns: 120
 
  # Optional: per-agent overrides
  agents:
    general-purpose:
      timeout_seconds: 1800 # 30 minutes for complex tasks
      max_turns: 160
    bash:
      timeout_seconds: 300 # 5 minutes for quick commands
      max_turns: 80

Per-agent overrides take priority over the global timeout_seconds and max_turns settings.

Concurrency limits

The SubagentLimitMiddleware controls how many subagents the Lead Agent can invoke in parallel in a single turn. This is controlled through the per-request configuration:

• subagent_enabled: whether subagent delegation is active for this session
• max_concurrent_subagents: maximum parallel task calls in one turn (default: 3)

If the agent tries to call more subagents than the limit allows, the middleware trims the excess calls.

ACP agents (external agents)

In addition to the built-in subagents, PengBao AI supports delegating to external agents through the Agent Connect Protocol (ACP). ACP allows PengBao AI to invoke agents running as separate processes (including third-party CLI tools wrapped with an ACP adapter).

Configure ACP agents in config.yaml:

acp_agents:
  claude_code:
    command: npx
    args: ["-y", "@zed-industries/claude-agent-acp"]
    description: Claude Code for implementation, refactoring, and debugging
    model: null
    # auto_approve_permissions: false
    # env:
    #   ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
 
  codex:
    command: npx
    args: ["-y", "@zed-industries/codex-acp"]
    description: Codex CLI for repository tasks and code generation
    model: null

The Lead Agent invokes ACP agents through the invoke_acp_agent built-in tool.

Custom agents as subagents

Custom agents created through the PengBao AI App UI can also be invoked as subagents using the task tool. When you specify agent="my-custom-agent", the runtime loads that agent’s configuration (skills, tool groups, model) and runs it as a subagent for the delegated task.