# Subagents (https://www.librechat.ai/docs/features/subagents)

Subagents let a LibreChat Agent spawn an isolated child run for focused work. The child agent gets its own context window and tool execution flow. The parent receives the child result without absorbing every intermediate tool call, trace, or verbose file operation into its own context.

Use subagents for:

- Research subtasks that may generate long intermediate output
- Review passes with a specialized agent
- Tool-heavy work that should stay outside the parent context
- Parallel-style decomposition where the parent coordinates and summarizes

## How Subagents Differ from Agent Chain

Agent Chain builds a multi-agent graph where agents pass results through configured chain steps. Subagents are spawned by an agent as a tool call during a run.

- **Agent Chain**: graph-level multi-agent workflow
- **Subagents**: runtime delegation from a parent agent to isolated child runs

Both can use existing agents, but subagents are designed for scoped delegation from inside a single agent's reasoning loop.

## Enable the Capability

The `subagents` capability is enabled by default. Admins can remove it from the agents endpoint capability list to disable the feature.

```yaml filename="librechat.yaml"
endpoints:
  agents:
    capabilities:
      - 'deferred_tools'
      - 'execute_code'
      - 'file_search'
      - 'web_search'
      - 'artifacts'
      - 'subagents'
      - 'actions'
      - 'context'
      - 'skills'
      - 'tools'
      - 'chain'
      - 'ocr'
```

## Configure an Agent

In the Agent Builder, open **Advanced Settings** and enable **Subagents**.

Available settings:

- **Enable subagents**: adds the subagent spawn tool to the agent.
- **Allow self-spawn**: lets the agent spawn a fresh copy of itself in an isolated context. This is enabled by default when subagents are enabled.
- **Additional subagents**: selects specific agents the parent may spawn.

Equivalent agent shape:

```yaml filename="agent subagents"
subagents:
  enabled: true
  allowSelf: true
  agent_ids:
    - 'agent_researcher'
    - 'agent_reviewer'
```

## Configure a Model Spec

Admins can also enable Subagents for ephemeral agents created from a model spec. This is useful when a model spec should behave like a focused agent profile without requiring users to create or select a persisted parent agent.

```yaml filename="modelSpecs / subagents"
modelSpecs:
  list:
    - name: 'research-assistant'
      label: 'Research Assistant'
      subagents:
        enabled: true
        allowSelf: true
        agent_ids: []
      preset:
        endpoint: 'agents'
        model: 'gpt-4o'
```

Only `enabled` and `allowSelf` are sent to clients in startup config. The `agent_ids` allowlist stays server-side and is validated against the shared `MAX_SUBAGENTS` limit. Client request payloads cannot supply or override model-spec Subagent configuration.

## Runtime Behavior

When subagents are enabled, the parent agent receives a `subagent` tool. The tool can spawn:

- `self`, when `allowSelf` is not false
- Any configured child agent in `agent_ids`

Child agents run with isolated context. Parent tool-search state and accumulated context are not copied into the child run. Child-run model usage is billed into the parent transaction and included in the parent's usage totals. The UI shows the child run as an expandable agent activity part with status, ticker updates, and the final result.

## Limits

LibreChat enforces these limits to keep subagent graphs bounded:

<OptionTable
  options={[
    ['MAX_SUBAGENTS', 'Number', 'Maximum explicit subagents per parent agent.', '10'],
    ['MAX_SUBAGENT_DEPTH', 'Number', 'Maximum explicit subagent hops from a root agent.', '5'],
    [
      'MAX_SUBAGENT_GRAPH_NODES',
      'Number',
      'Maximum unique explicit subagent targets loaded at runtime.',
      '50',
    ],
    [
      'MAX_SUBAGENT_RUN_CONFIGS',
      'Number',
      'Maximum expanded subagent configurations embedded into one run request.',
      '100',
    ],
  ]}
/>

## Access Control

Configured child agents must be visible to the user. If the user lacks view access to a referenced agent, LibreChat skips that subagent. For create and update requests, invalid or unauthorized `subagents.agent_ids` entries are rejected.

## Design Tips

- Enable self-spawn when the parent agent is already well-scoped and just needs a fresh context for a subtask.
- Add specific child agents when the task needs a different model, instruction set, tool set, or skill allowlist.
- Keep child descriptions clear. The parent uses each child name and description to choose the right delegation target.
- Use subagents for intermediate work that should return a compact result, not for permanent handoffs to another conversation path.