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.

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:

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.

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:

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.