From b09a341b941e00751126556e7db36399c14db744 Mon Sep 17 00:00:00 2001 From: Will Wilson Date: Sun, 8 Mar 2026 21:38:45 +0000 Subject: [PATCH 1/2] docs: add Mixture-of-Agents (agent chaining) configuration guide Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/docs/features/agent-chains.mdx | 129 ++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/docs/features/agent-chains.mdx diff --git a/docs/docs/features/agent-chains.mdx b/docs/docs/features/agent-chains.mdx new file mode 100644 index 0000000000..d59d2a275f --- /dev/null +++ b/docs/docs/features/agent-chains.mdx @@ -0,0 +1,129 @@ +--- +title: Agent Chains (Mixture of Agents) +description: Configure agent-to-agent delegation (MoA) in LibreChat +--- + +# Agent Chains (Mixture of Agents) + +LibreChat supports **agent chaining** (also called Mixture of Agents / MoA), where a primary "orchestrator" agent delegates tasks to specialised "worker" agents. Each specialist is optimised for a narrow domain with a focused system prompt and minimal toolset. + +## Architecture + +``` +User Message + │ + ▼ +┌─────────────┐ +│ Orchestrator │ ← Handles all requests; decides who processes each task +│ Agent │ +└──────┬──────┘ + │ delegates + ▼ +┌──────────────────────────────────┐ +│ Specialist Agents │ +│ ┌──────────┐ ┌──────────────┐ │ +│ │ Research │ │ Action Agent │ │ +│ └──────────┘ └──────────────┘ │ +│ ┌──────────┐ ┌──────────────┐ │ +│ │ Writer │ │ Data Analyst │ │ +│ └──────────┘ └──────────────┘ │ +└──────────────────────────────────┘ + │ + ▼ +User sees consolidated response +``` + +## How it works in LibreChat v0.8.3+ + +1. **Agents are created in Agent Builder UI** — there is no JSON import; each agent must be created manually via the interface at `/agent-builder` +2. **Specialist agents appear as tools** — once created, any agent with the `tools` capability can call other agents as tools +3. **Context is passed explicitly** — the orchestrator passes relevant information in its delegation call + +## Minimal toolset principle + +Give each specialist agent **only** the tools it needs. An over-tooled agent is slower and more likely to call the wrong tool. + +| Agent Type | Recommended Tools | +|------------|------------------| +| Research | perplexica_search, navigate, snapshot | +| Action | domain-specific APIs, write operations | +| Summariser | No tools (just processes input text) | +| Data | execute_code, file_search | + +## Step-by-step setup + +### 1. Create specialist agents first + +In LibreChat, go to **Agent Builder** → **+ New Agent** and create each specialist with: +- A focused, single-domain system prompt +- Only the tools relevant to that domain +- A clear agent name that describes its role + +Note each agent's ID (shown in the URL or agent settings panel) after saving. + +### 2. Create the orchestrator agent + +Create a main orchestrator agent with: +- The `tools` capability enabled +- All specialist agents listed as available tools +- A system prompt that explains the delegation rules + +**Delegation rule example for orchestrator system prompt:** + +``` +You are an orchestrator. For each user request, decide which specialist to call: +- Research questions, current events, web searches → call ResearchAgent +- Data analysis, calculations, code → call DataAgent +- Document writing, formatting → call WriterAgent + +ALWAYS complete tool calls before responding to the user. +NEVER generate placeholder text — call the tool immediately. +``` + +### 3. Enable the `chain` capability + +In the orchestrator's Agent Builder configuration, enable the **Chain** capability. This allows the agent to invoke other agents as tools. + +## Delegation patterns + +### Parallel delegation +Call multiple specialists and synthesise their outputs: +``` +User: "Summarise today's AI news and write a tweet about it" +→ Orchestrator calls ResearchAgent("today's AI news") +→ Orchestrator calls WriterAgent(research_result, "write tweet") +→ Orchestrator presents combined result +``` + +### Sequential delegation +Pass output from one specialist as input to the next: +``` +User: "Find the current Bitcoin price and analyse the trend" +→ Orchestrator calls ResearchAgent("Bitcoin price today") +→ Orchestrator calls DataAgent(price_data, "analyse trend") +→ Present analysis +``` + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| Specialist agent not appearing as a tool | Ensure the specialist was saved in Agent Builder; refresh the orchestrator | +| Orchestrator generates text instead of calling agent | Add explicit delegation instructions to system prompt; enable `tools` capability | +| Infinite loop between agents | Set `recursionLimit` in `librechat.yaml` agents config (default: 25) | +| Agent calls wrong specialist | Make delegation rules more specific in orchestrator system prompt | + +## librechat.yaml configuration + +```yaml +agents: + disableBuilder: false + recursionLimit: 25 + maxContextTokens: 32000 + capabilities: + - execute_code + - file_search + - artifacts + - tools + - chain +``` From a927f3a7603bd4bc07a1d60f51576fe2a9ac1572 Mon Sep 17 00:00:00 2001 From: Will Wilson Date: Sun, 8 Mar 2026 22:10:25 +0000 Subject: [PATCH 2/2] docs: fix chain architecture, YAML structure, recursionLimit, tool labels Address review feedback: - Correct chain capability description (UI config, not delegation mechanism) - Fix agent-to-agent linking description (edges/agent_ids, not tool registry) - Fix YAML to nest under endpoints.agents, remove maxContextTokens - Update recursionLimit to correct default - Clarify custom MCP tool IDs vs built-in tools Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/docs/features/agent-chains.mdx | 34 ++++++++++++++++------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/docs/features/agent-chains.mdx b/docs/docs/features/agent-chains.mdx index d59d2a275f..ae9582441b 100644 --- a/docs/docs/features/agent-chains.mdx +++ b/docs/docs/features/agent-chains.mdx @@ -36,7 +36,7 @@ User sees consolidated response ## How it works in LibreChat v0.8.3+ 1. **Agents are created in Agent Builder UI** — there is no JSON import; each agent must be created manually via the interface at `/agent-builder` -2. **Specialist agents appear as tools** — once created, any agent with the `tools` capability can call other agents as tools +2. **Specialist agents are linked via agent chains** — the orchestrator is configured with edges that reference other agents by `agent_ids`. Agents do not appear as built-in tools in the standard tool registry. 3. **Context is passed explicitly** — the orchestrator passes relevant information in its delegation call ## Minimal toolset principle @@ -45,7 +45,7 @@ Give each specialist agent **only** the tools it needs. An over-tooled agent is | Agent Type | Recommended Tools | |------------|------------------| -| Research | perplexica_search, navigate, snapshot | +| Research | perplexica_search, navigate, snapshot (Custom MCP tools) | | Action | domain-specific APIs, write operations | | Summariser | No tools (just processes input text) | | Data | execute_code, file_search | @@ -80,9 +80,13 @@ ALWAYS complete tool calls before responding to the user. NEVER generate placeholder text — call the tool immediately. ``` -### 3. Enable the `chain` capability +### 3. (Optional) Enable the Chain Capability -In the orchestrator's Agent Builder configuration, enable the **Chain** capability. This allows the agent to invoke other agents as tools. +In the orchestrator's Agent Builder configuration, the **Chain** capability controls the +Agent Builder UI for configuring sequential chains between this agent and specific other +agents (via `agent_ids`). It does **not** by itself enable agent-as-a-tool delegation — +that behavior comes from combining the **tools** capability with properly configured agent +handoffs. ## Delegation patterns @@ -110,20 +114,20 @@ User: "Find the current Bitcoin price and analyse the trend" |-------|----------| | Specialist agent not appearing as a tool | Ensure the specialist was saved in Agent Builder; refresh the orchestrator | | Orchestrator generates text instead of calling agent | Add explicit delegation instructions to system prompt; enable `tools` capability | -| Infinite loop between agents | Set `recursionLimit` in `librechat.yaml` agents config (default: 25) | +| Infinite loop between agents | Set `recursionLimit` in `librechat.yaml` under `endpoints.agents` (no hardcoded default; recommended: 50) | | Agent calls wrong specialist | Make delegation rules more specific in orchestrator system prompt | ## librechat.yaml configuration ```yaml -agents: - disableBuilder: false - recursionLimit: 25 - maxContextTokens: 32000 - capabilities: - - execute_code - - file_search - - artifacts - - tools - - chain +endpoints: + agents: + disableBuilder: false + recursionLimit: 50 + capabilities: + - execute_code + - file_search + - artifacts + - tools + - chain ```