Subagents

A subagent is a child run that an agent starts in the middle of its own work. The child gets a clean context window, does the job (searching, reading files, calling tools), and returns only its result. The parent's context stays small, which matters when the intermediate work produces pages of tool output the parent never needs to see.

Reach for subagents when a task splits into pieces that each generate a lot of noise: researching several topics, reviewing a set of files, or running a tool-heavy check before the main answer.

Turn it on for an agent

Self-spawn is enough when the agent is already set up for the job and just needs a clean slate. Add other agents when a subtask needs a different model, different instructions, or different tools, for example a cheap fast model for searches or a reviewer agent with a strict checklist. The parent chooses among them by name and description, so give each one a description that says what it is for.

Children are only loaded when the parent actually picks them, so listing several costs nothing until one runs. An agent can list up to 10 subagents by default. If you turn off self-spawn and list no agents, there is nothing to spawn and the builder tells you so.

Sharing files with subagents

If your admin has enabled it, a Share files with subagents switch appears. With it on, files attached to the current message are available to the subagents the parent starts. Files a subagent creates in the sandbox stay private to it until it chooses which versions to hand back.

What you see in the chat

Each subagent run shows up in the parent's reply as a compact row with the child's name and status: Running agent while it works, then Ran agent when it is done. Open it to follow the child in the activity side panel, or ignore it and read the parent's answer. A cancelled run shows Agent stopped, and a failed one Agent failed. Children started in the background (see below) are grouped in an Agent activity block instead.

How it behaves

• The child starts with its own context. It does not inherit the parent's conversation history or the tools the parent discovered with tool search; it gets the task the parent writes for it.
• Token usage from child runs counts toward your balance. Children that finish while the parent is still running are added to the parent's totals; detached children that finish later are recorded on their own.
• A child agent you no longer have access to is skipped. You cannot add an agent you cannot see. Access and the child's saved configuration are checked again when it starts; if either changed during the run, the child does not run.
• Each child keeps its own model, instructions, tools, MCP credentials, skills, files, and memory.
• The step limit applies to subagents too, so a low Max Agent Steps value also limits how much a child can do.
• Subagents can start their own subagents, up to 5 levels deep.

Saved Agent teams

A parent can also start a saved team: several agents wired together as one small workflow, such as a researcher whose findings go to a reviewer. The team runs as one isolated child, and only the result agent's answer comes back to the parent. A team can have up to 32 members. If any member is missing or you cannot see it, the whole team is skipped rather than run partly.

Teams are defined through the API, not in the Agent Builder. The builder keeps a team intact when you edit the agent's other subagent settings. The definition format is in the agents endpoint configuration.

Detached Subagent Threads

If your admin has enabled background execution, the parent can start a subagent and carry on without waiting for it. The child's work is saved as a view-only thread that you reach from the parent's activity panel; it does not show up in your chat list or search. Very long histories are trimmed, and the panel says so when earlier activity is not shown.

Control a running child

While a detached child is running, type in the activity panel's composer to guide it:

• Steer adds your guidance at the child's next safe point. This is the default.
• Queue holds it for the child's next turn.
• Interrupt stops the current step and applies the guidance.
• With nothing typed, the send button becomes Cancel task.

Each message shows whether it was applied. Queued guidance can be taken back with Withdraw before the child picks it up. Guidance is limited to 4 KB. When a direct child has finished, Continue in a new chat copies its conversation into a normal chat you can keep working in; the original thread stays read-only.

Shared conversations show only the activity included in the share, without any controls.

Automatic parent continuation

When a detached child finishes, LibreChat by default wakes the parent agent up on the same branch with the result, shown as a collapsible task card. If the parent is still busy, the wake-up waits for it. Cancelled children do not wake the parent, and this only works for saved agents, not ones created from a model spec. Your admin can turn it off, in which case the parent has to check on the child itself.

Children that external systems drive through the Agents API show up the same way, as a row under the parent message that opens the same panel.

Subagents compared with handoffs

A subagent returns control to the parent: the parent asks, the child answers, and the parent writes the reply. A handoff passes the conversation to another agent, which then replies itself. Use a subagent for a subtask, a handoff to route to a specialist.

Setup

Subagents are available by default. Admins can turn them off with the subagents capability, raise the per-agent limit with maxSubagents, enable file sharing, and allow detached children with the opt-in run_in_background capability, all in the agents endpoint configuration. Automatic parent continuation is controlled by backgroundTasks. They can also be enabled for a model spec without a saved parent agent; see Model Specs.