⏸ refactor: Improve UX for Parallel Streams (Multi-Convo) (#11096)

* 🌊 feat: Implement multi-conversation feature with added conversation context and payload adjustments * refactor: Replace isSubmittingFamily with isSubmitting across message components for consistency * feat: Add loadAddedAgent and processAddedConvo for multi-conversation agent execution * refactor: Update ContentRender usage to conditionally render PlaceholderRow based on isLast and isSubmitting * WIP: first pass, sibling index * feat: Enhance multi-conversation support with agent tracking and display improvements * refactor: Introduce isEphemeralAgentId utility and update related logic for agent handling * refactor: Implement createDualMessageContent utility for sibling message display and enhance useStepHandler for added conversations * refactor: duplicate tools for added agent if ephemeral and primary agent is also ephemeral * chore: remove deprecated multimessage rendering * refactor: enhance dual message content creation and agent handling for parallel rendering * refactor: streamline message rendering and submission handling by removing unused state and optimizing conditional logic * refactor: adjust content handling in parallel mode to utilize existing content for improved agent display * refactor: update @librechat/agents dependency to version 3.0.53 * refactor: update @langchain/core and @librechat/agents dependencies to latest versions * refactor: remove deprecated @langchain/core dependency from package.json * chore: remove unused SearchToolConfig and GetSourcesParams types from web.ts * refactor: remove unused message properties from Message component * refactor: enhance parallel content handling with groupId support in ContentParts and useStepHandler * refactor: implement parallel content styling in Message, MessageRender, and ContentRender components. use explicit model name * refactor: improve agent ID handling in createDualMessageContent for dual message display * refactor: simplify title generation in AddedConvo by removing unused sender and preset logic * refactor: replace string interpolation with cn utility for className in HoverButtons component * refactor: enhance agent ID handling by adding suffix management for parallel agents and updating related components * refactor: enhance column ordering in ContentParts by sorting agents with suffix management * refactor: update @librechat/agents dependency to version 3.0.55 * feat: implement parallel content rendering with metadata support - Added `ParallelContentRenderer` and `ParallelColumns` components for rendering messages in parallel based on groupId and agentId. - Introduced `contentMetadataMap` to store metadata for each content part, allowing efficient parallel content detection. - Updated `Message` and `ContentRender` components to utilize the new metadata structure for rendering. - Modified `useStepHandler` to manage content indices and metadata during message processing. - Enhanced `IJobStore` interface and its implementations to support storing and retrieving content metadata. - Updated data schemas to include `contentMetadataMap` for messages, enabling multi-agent and parallel execution scenarios. * refactor: update @librechat/agents dependency to version 3.0.56 * refactor: remove unused EPHEMERAL_AGENT_ID constant and simplify agent ID check * refactor: enhance multi-agent message processing and primary agent determination * refactor: implement branch message functionality for parallel responses * refactor: integrate added conversation retrieval into message editing and regeneration processes * refactor: remove unused isCard and isMultiMessage props from MessageRender and ContentRender components * refactor: update @librechat/agents dependency to version 3.0.60 * refactor: replace usage of EPHEMERAL_AGENT_ID constant with isEphemeralAgentId function for improved clarity and consistency * refactor: standardize agent ID format in tests for consistency * chore: move addedConvo property to the correct position in payload construction * refactor: rename agent_id values in loadAgent tests for clarity * chore: reorder props in ContentParts component for improved readability * refactor: rename variable 'content' to 'result' for clarity in RedisJobStore tests * refactor: streamline useMessageActions by removing duplicate handleFeedback assignment * chore: revert placeholder rendering logic MessageRender and ContentRender components to original * refactor: implement useContentMetadata hook for optimized content metadata handling * refactor: remove contentMetadataMap and related logic from the codebase and revert back to agentId/groupId in content parts - Eliminated contentMetadataMap from various components and services, simplifying the handling of message content. - Updated functions to directly access agentId and groupId from content parts instead of relying on a separate metadata map. - Adjusted related hooks and components to reflect the removal of contentMetadataMap, ensuring consistent handling of message content. - Updated tests and documentation to align with the new structure of message content handling. * refactor: remove logging from groupParallelContent function to clean up output * refactor: remove model parameter from TBranchMessageRequest type for simplification * refactor: enhance branch message creation by stripping metadata for standalone content * chore: streamline branch message creation by simplifying content filtering and removing unnecessary metadata checks * refactor: include attachments in branch message creation for improved content handling * refactor: streamline agent content processing by consolidating primary agent identification and filtering logic * refactor: simplify multi-agent message processing by creating a dedicated mapping method and enhancing content filtering * refactor: remove unused parameter from loadEphemeralAgent function for cleaner code * refactor: update groupId handling in metadata to only set when provided by the server
2026-01-16 23:45:33 +01:00 · 2025-12-25 01:43:54 -05:00 · 2025-12-25 01:43:54 -05:00 · 439bc98682
commit 439bc98682
parent 9b6e7cabc9
74 changed files with 2174 additions and 957 deletions
--- a/api/app/clients/BaseClient.js
+++ b/api/app/clients/BaseClient.js
@ -18,6 +18,7 @@ const {
  EModelEndpoint,
  isParamEndpoint,
  isAgentsEndpoint,
+  isEphemeralAgentId,
  supportsBalanceCheck,
 } = require('librechat-data-provider');
 const {
@ -714,7 +715,7 @@ class BaseClient {
      iconURL: this.options.iconURL,
      endpoint: this.options.endpoint,
      ...(this.metadata ?? {}),
-      metadata,
+      metadata: Object.keys(metadata ?? {}).length > 0 ? metadata : undefined,
    };

    if (typeof completion === 'string') {
@ -969,7 +970,7 @@ class BaseClient {
    const hasNonEphemeralAgent =
      isAgentsEndpoint(this.options.endpoint) &&
      endpointOptions?.agent_id &&
-      endpointOptions.agent_id !== Constants.EPHEMERAL_AGENT_ID;
+      !isEphemeralAgentId(endpointOptions.agent_id);
    if (hasNonEphemeralAgent) {
      exceptions.add('model');
    }
--- a/api/models/Agent.js
+++ b/api/models/Agent.js
@ -1,8 +1,18 @@
 const mongoose = require('mongoose');
 const crypto = require('node:crypto');
 const { logger } = require('@librechat/data-schemas');
-const { ResourceType, SystemRoles, Tools, actionDelimiter } = require('librechat-data-provider');
-const { GLOBAL_PROJECT_NAME, EPHEMERAL_AGENT_ID, mcp_all, mcp_delimiter } =
+const { getCustomEndpointConfig } = require('@librechat/api');
+const {
+  Tools,
+  SystemRoles,
+  ResourceType,
+  actionDelimiter,
+  isAgentsEndpoint,
+  getResponseSender,
+  isEphemeralAgentId,
+  encodeEphemeralAgentId,
+} = require('librechat-data-provider');
+const { GLOBAL_PROJECT_NAME, mcp_all, mcp_delimiter } =
  require('librechat-data-provider').Constants;
 const {
  removeAgentFromAllProjects,
@ -92,7 +102,7 @@ const getAgents = async (searchParameter) => await Agent.find(searchParameter).l
 * @param {import('@librechat/agents').ClientOptions} [params.model_parameters]
 * @returns {Promise<Agent|null>} The agent document as a plain object, or null if not found.
 */
-const loadEphemeralAgent = async ({ req, spec, agent_id, endpoint, model_parameters: _m }) => {
+const loadEphemeralAgent = async ({ req, spec, endpoint, model_parameters: _m }) => {
  const { model, ...model_parameters } = _m;
  const modelSpecs = req.config?.modelSpecs?.list;
  /** @type {TModelSpec | null} */
@ -139,8 +149,28 @@ const loadEphemeralAgent = async ({ req, spec, agent_id, endpoint, model_paramet
  }

  const instructions = req.body.promptPrefix;
+
+  // Compute display name using getResponseSender (same logic used for addedConvo agents)
+  const appConfig = req.config;
+  let endpointConfig = appConfig?.endpoints?.[endpoint];
+  if (!isAgentsEndpoint(endpoint) && !endpointConfig) {
+    try {
+      endpointConfig = getCustomEndpointConfig({ endpoint, appConfig });
+    } catch (err) {
+      logger.error('[loadEphemeralAgent] Error getting custom endpoint config', err);
+    }
+  }
+
+  const sender = getResponseSender({
+    modelLabel: model_parameters?.modelLabel,
+    modelDisplayLabel: endpointConfig?.modelDisplayLabel,
+  });
+
+  // Encode ephemeral agent ID with endpoint, model, and computed sender for display
+  const ephemeralId = encodeEphemeralAgentId({ endpoint, model, sender });
+
  const result = {
-    id: agent_id,
+    id: ephemeralId,
    instructions,
    provider: endpoint,
    model_parameters,
@ -169,8 +199,8 @@ const loadAgent = async ({ req, spec, agent_id, endpoint, model_parameters }) =>
  if (!agent_id) {
    return null;
  }
-  if (agent_id === EPHEMERAL_AGENT_ID) {
-    return await loadEphemeralAgent({ req, spec, agent_id, endpoint, model_parameters });
+  if (isEphemeralAgentId(agent_id)) {
+    return await loadEphemeralAgent({ req, spec, endpoint, model_parameters });
  }
  const agent = await getAgent({
    id: agent_id,
--- a/api/models/Agent.spec.js
+++ b/api/models/Agent.spec.js
@ -1960,7 +1960,8 @@ describe('models/Agent', () => {
      });

      if (result) {
-        expect(result.id).toBe(EPHEMERAL_AGENT_ID);
+        // Ephemeral agent ID is encoded with endpoint and model
+        expect(result.id).toBe('openai__gpt-4');
        expect(result.instructions).toBe('Test instructions');
        expect(result.provider).toBe('openai');
        expect(result.model).toBe('gpt-4');
@ -1978,7 +1979,7 @@ describe('models/Agent', () => {
      const mockReq = { user: { id: 'user123' } };
      const result = await loadAgent({
        req: mockReq,
-        agent_id: 'non_existent_agent',
+        agent_id: 'agent_non_existent',
        endpoint: 'openai',
        model_parameters: { model: 'gpt-4' },
      });
@ -2105,7 +2106,7 @@ describe('models/Agent', () => {
      test('should handle loadAgent with malformed req object', async () => {
        const result = await loadAgent({
          req: null,
-          agent_id: 'test',
+          agent_id: 'agent_test',
          endpoint: 'openai',
          model_parameters: { model: 'gpt-4' },
        });
--- a/api/models/loadAddedAgent.js
+++ b/api/models/loadAddedAgent.js
@ -0,0 +1,218 @@
+const { logger } = require('@librechat/data-schemas');
+const { getCustomEndpointConfig } = require('@librechat/api');
+const {
+  Tools,
+  Constants,
+  isAgentsEndpoint,
+  getResponseSender,
+  isEphemeralAgentId,
+  appendAgentIdSuffix,
+  encodeEphemeralAgentId,
+} = require('librechat-data-provider');
+const { getMCPServerTools } = require('~/server/services/Config');
+
+const { mcp_all, mcp_delimiter } = Constants;
+
+/**
+ * Constant for added conversation agent ID
+ */
+const ADDED_AGENT_ID = 'added_agent';
+
+/**
+ * Get an agent document based on the provided ID.
+ * @param {Object} searchParameter - The search parameters to find the agent.
+ * @param {string} searchParameter.id - The ID of the agent.
+ * @returns {Promise<import('librechat-data-provider').Agent|null>}
+ */
+let getAgent;
+
+/**
+ * Set the getAgent function (dependency injection to avoid circular imports)
+ * @param {Function} fn
+ */
+const setGetAgent = (fn) => {
+  getAgent = fn;
+};
+
+/**
+ * Load an agent from an added conversation (TConversation).
+ * Used for multi-convo parallel agent execution.
+ *
+ * @param {Object} params
+ * @param {import('express').Request} params.req
+ * @param {import('librechat-data-provider').TConversation} params.conversation - The added conversation
+ * @param {import('librechat-data-provider').Agent} [params.primaryAgent] - The primary agent (used to duplicate tools when both are ephemeral)
+ * @returns {Promise<import('librechat-data-provider').Agent|null>} The agent config as a plain object, or null if invalid.
+ */
+const loadAddedAgent = async ({ req, conversation, primaryAgent }) => {
+  if (!conversation) {
+    return null;
+  }
+
+  // If there's an agent_id, load the existing agent
+  if (conversation.agent_id && !isEphemeralAgentId(conversation.agent_id)) {
+    if (!getAgent) {
+      throw new Error('getAgent not initialized - call setGetAgent first');
+    }
+    const agent = await getAgent({
+      id: conversation.agent_id,
+    });
+
+    if (!agent) {
+      logger.warn(`[loadAddedAgent] Agent ${conversation.agent_id} not found`);
+      return null;
+    }
+
+    agent.version = agent.versions ? agent.versions.length : 0;
+    // Append suffix to distinguish from primary agent (matches ephemeral format)
+    // This is needed when both agents have the same ID or for consistent parallel content attribution
+    agent.id = appendAgentIdSuffix(agent.id, 1);
+    return agent;
+  }
+
+  // Otherwise, create an ephemeral agent config from the conversation
+  const { model, endpoint, promptPrefix, spec, ...rest } = conversation;
+
+  if (!endpoint || !model) {
+    logger.warn('[loadAddedAgent] Missing required endpoint or model for ephemeral agent');
+    return null;
+  }
+
+  // If both primary and added agents are ephemeral, duplicate tools from primary agent
+  const primaryIsEphemeral = primaryAgent && isEphemeralAgentId(primaryAgent.id);
+  if (primaryIsEphemeral && Array.isArray(primaryAgent.tools)) {
+    // Get display name using getResponseSender
+    const appConfig = req.config;
+    let endpointConfig = appConfig?.endpoints?.[endpoint];
+    if (!isAgentsEndpoint(endpoint) && !endpointConfig) {
+      try {
+        endpointConfig = getCustomEndpointConfig({ endpoint, appConfig });
+      } catch (err) {
+        logger.error('[loadAddedAgent] Error getting custom endpoint config', err);
+      }
+    }
+
+    const sender = getResponseSender({
+      modelLabel: rest.modelLabel,
+      modelDisplayLabel: endpointConfig?.modelDisplayLabel,
+    });
+
+    const ephemeralId = encodeEphemeralAgentId({ endpoint, model, sender, index: 1 });
+
+    return {
+      id: ephemeralId,
+      instructions: promptPrefix || '',
+      provider: endpoint,
+      model_parameters: {},
+      model,
+      tools: [...primaryAgent.tools],
+    };
+  }
+
+  // Extract ephemeral agent options from conversation if present
+  const ephemeralAgent = rest.ephemeralAgent;
+  const mcpServers = new Set(ephemeralAgent?.mcp);
+  const userId = req.user?.id;
+
+  // Check model spec for MCP servers
+  const modelSpecs = req.config?.modelSpecs?.list;
+  let modelSpec = null;
+  if (spec != null && spec !== '') {
+    modelSpec = modelSpecs?.find((s) => s.name === spec) || null;
+  }
+  if (modelSpec?.mcpServers) {
+    for (const mcpServer of modelSpec.mcpServers) {
+      mcpServers.add(mcpServer);
+    }
+  }
+
+  /** @type {string[]} */
+  const tools = [];
+  if (ephemeralAgent?.execute_code === true || modelSpec?.executeCode === true) {
+    tools.push(Tools.execute_code);
+  }
+  if (ephemeralAgent?.file_search === true || modelSpec?.fileSearch === true) {
+    tools.push(Tools.file_search);
+  }
+  if (ephemeralAgent?.web_search === true || modelSpec?.webSearch === true) {
+    tools.push(Tools.web_search);
+  }
+
+  const addedServers = new Set();
+  if (mcpServers.size > 0) {
+    for (const mcpServer of mcpServers) {
+      if (addedServers.has(mcpServer)) {
+        continue;
+      }
+      const serverTools = await getMCPServerTools(userId, mcpServer);
+      if (!serverTools) {
+        tools.push(`${mcp_all}${mcp_delimiter}${mcpServer}`);
+        addedServers.add(mcpServer);
+        continue;
+      }
+      tools.push(...Object.keys(serverTools));
+      addedServers.add(mcpServer);
+    }
+  }
+
+  // Build model_parameters from conversation fields
+  const model_parameters = {};
+  const paramKeys = [
+    'temperature',
+    'top_p',
+    'topP',
+    'topK',
+    'presence_penalty',
+    'frequency_penalty',
+    'maxOutputTokens',
+    'maxTokens',
+    'max_tokens',
+  ];
+
+  for (const key of paramKeys) {
+    if (rest[key] != null) {
+      model_parameters[key] = rest[key];
+    }
+  }
+
+  // Get endpoint config for modelDisplayLabel (same pattern as initialize.js)
+  const appConfig = req.config;
+  let endpointConfig = appConfig?.endpoints?.[endpoint];
+  if (!isAgentsEndpoint(endpoint) && !endpointConfig) {
+    try {
+      endpointConfig = getCustomEndpointConfig({ endpoint, appConfig });
+    } catch (err) {
+      logger.error('[loadAddedAgent] Error getting custom endpoint config', err);
+    }
+  }
+
+  // Compute display name using getResponseSender (same logic used for main agent)
+  const sender = getResponseSender({
+    modelLabel: rest.modelLabel,
+    modelDisplayLabel: endpointConfig?.modelDisplayLabel,
+  });
+
+  /** Encoded ephemeral agent ID with endpoint, model, sender, and index=1 to distinguish from primary */
+  const ephemeralId = encodeEphemeralAgentId({ endpoint, model, sender, index: 1 });
+
+  const result = {
+    id: ephemeralId,
+    instructions: promptPrefix || '',
+    provider: endpoint,
+    model_parameters,
+    model,
+    tools,
+  };
+
+  if (ephemeralAgent?.artifacts != null && ephemeralAgent.artifacts) {
+    result.artifacts = ephemeralAgent.artifacts;
+  }
+
+  return result;
+};
+
+module.exports = {
+  ADDED_AGENT_ID,
+  loadAddedAgent,
+  setGetAgent,
+};
--- a/api/package.json
+++ b/api/package.json
@ -42,8 +42,8 @@
    "@azure/storage-blob": "^12.27.0",
    "@googleapis/youtube": "^20.0.0",
    "@keyv/redis": "^4.3.3",
-    "@langchain/core": "^0.3.79",
-    "@librechat/agents": "^3.0.52",
+    "@langchain/core": "^0.3.80",
+    "@librechat/agents": "^3.0.61",
    "@librechat/api": "*",
    "@librechat/data-schemas": "*",
    "@microsoft/microsoft-graph-client": "^3.0.7",
--- a/api/server/cleanup.js
+++ b/api/server/cleanup.js
@ -350,9 +350,6 @@ function disposeClient(client) {
    if (client.agentConfigs) {
      client.agentConfigs = null;
    }
-    if (client.agentIdMap) {
-      client.agentIdMap = null;
-    }
    if (client.artifactPromises) {
      client.artifactPromises = null;
    }
--- a/api/server/controllers/agents/client.js
+++ b/api/server/controllers/agents/client.js
@ -37,14 +37,13 @@ const {
  EModelEndpoint,
  PermissionTypes,
  isAgentsEndpoint,
-  AgentCapabilities,
+  isEphemeralAgentId,
  bedrockInputSchema,
  removeNullishValues,
 } = require('librechat-data-provider');
 const { spendTokens, spendStructuredTokens } = require('~/models/spendTokens');
 const { encodeAndFormat } = require('~/server/services/Files/images/encode');
 const { createContextHandlers } = require('~/app/clients/prompts');
-const { checkCapability } = require('~/server/services/Config');
 const { getConvoFiles } = require('~/models/Conversation');
 const BaseClient = require('~/app/clients/BaseClient');
 const { getRoleByName } = require('~/models/Role');
@ -96,59 +95,101 @@ function logToolError(graph, error, toolId) {
  });
 }

+/** Regex pattern to match agent ID suffix (____N) */
+const AGENT_SUFFIX_PATTERN = /____(\d+)$/;
+
 /**
- * Applies agent labeling to conversation history when multi-agent patterns are detected.
- * Labels content parts by their originating agent to prevent identity confusion.
+ * Creates a mapMethod for getMessagesForConversation that processes agent content.
+ * - Strips agentId/groupId metadata from all content
+ * - For multi-agent: filters to primary agent content only (no suffix or lowest suffix)
+ * - For multi-agent: applies agent labels to content
 *
- * @param {TMessage[]} orderedMessages - The ordered conversation messages
- * @param {Agent} primaryAgent - The primary agent configuration
- * @param {Map<string, Agent>} agentConfigs - Map of additional agent configurations
- * @returns {TMessage[]} Messages with agent labels applied where appropriate
+ * @param {Agent} primaryAgent - Primary agent configuration
+ * @param {Map<string, Agent>} [agentConfigs] - Additional agent configurations
+ * @returns {(message: TMessage) => TMessage} Map method for processing messages
 */
-function applyAgentLabelsToHistory(orderedMessages, primaryAgent, agentConfigs) {
-  const shouldLabelByAgent = (primaryAgent.edges?.length ?? 0) > 0 || (agentConfigs?.size ?? 0) > 0;
-
-  if (!shouldLabelByAgent) {
-    return orderedMessages;
-  }
-
-  const processedMessages = [];
-
-  for (let i = 0; i < orderedMessages.length; i++) {
-    const message = orderedMessages[i];
-
-    /** @type {Record<string, string>} */
-    const agentNames = { [primaryAgent.id]: primaryAgent.name || 'Assistant' };
+function createMultiAgentMapper(primaryAgent, agentConfigs) {
+  const hasMultipleAgents = (primaryAgent.edges?.length ?? 0) > 0 || (agentConfigs?.size ?? 0) > 0;

+  /** @type {Record<string, string> | null} */
+  let agentNames = null;
+  if (hasMultipleAgents) {
+    agentNames = { [primaryAgent.id]: primaryAgent.name || 'Assistant' };
    if (agentConfigs) {
      for (const [agentId, agentConfig] of agentConfigs.entries()) {
        agentNames[agentId] = agentConfig.name || agentConfig.id;
      }
    }
-
-    if (
-      !message.isCreatedByUser &&
-      message.metadata?.agentIdMap &&
-      Array.isArray(message.content)
-    ) {
-      try {
-        const labeledContent = labelContentByAgent(
-          message.content,
-          message.metadata.agentIdMap,
-          agentNames,
-        );
-
-        processedMessages.push({ ...message, content: labeledContent });
-      } catch (error) {
-        logger.error('[AgentClient] Error applying agent labels to message:', error);
-        processedMessages.push(message);
-      }
-    } else {
-      processedMessages.push(message);
-    }
  }

-  return processedMessages;
+  return (message) => {
+    if (message.isCreatedByUser || !Array.isArray(message.content)) {
+      return message;
+    }
+
+    // Find primary agent ID (no suffix, or lowest suffix number) - only needed for multi-agent
+    let primaryAgentId = null;
+    let hasAgentMetadata = false;
+
+    if (hasMultipleAgents) {
+      let lowestSuffixIndex = Infinity;
+      for (const part of message.content) {
+        const agentId = part?.agentId;
+        if (!agentId) {
+          continue;
+        }
+        hasAgentMetadata = true;
+
+        const suffixMatch = agentId.match(AGENT_SUFFIX_PATTERN);
+        if (!suffixMatch) {
+          primaryAgentId = agentId;
+          break;
+        }
+        const suffixIndex = parseInt(suffixMatch[1], 10);
+        if (suffixIndex < lowestSuffixIndex) {
+          lowestSuffixIndex = suffixIndex;
+          primaryAgentId = agentId;
+        }
+      }
+    } else {
+      // Single agent: just check if any metadata exists
+      hasAgentMetadata = message.content.some((part) => part?.agentId || part?.groupId);
+    }
+
+    if (!hasAgentMetadata) {
+      return message;
+    }
+
+    try {
+      /** @type {Array<TMessageContentParts>} */
+      const filteredContent = [];
+      /** @type {Record<number, string>} */
+      const agentIdMap = {};
+
+      for (const part of message.content) {
+        const agentId = part?.agentId;
+        // For single agent: include all parts; for multi-agent: filter to primary
+        if (!hasMultipleAgents || !agentId || agentId === primaryAgentId) {
+          const newIndex = filteredContent.length;
+          const { agentId: _a, groupId: _g, ...cleanPart } = part;
+          filteredContent.push(cleanPart);
+          if (agentId && hasMultipleAgents) {
+            agentIdMap[newIndex] = agentId;
+          }
+        }
+      }
+
+      const finalContent =
+        Object.keys(agentIdMap).length > 0 && agentNames
+          ? labelContentByAgent(filteredContent, agentIdMap, agentNames)
+          : filteredContent;
+
+      return { ...message, content: finalContent };
+    } catch (error) {
+      logger.error('[AgentClient] Error processing multi-agent message:', error);
+      return message;
+    }
+  };
 }

 class AgentClient extends BaseClient {
@ -200,8 +241,6 @@ class AgentClient extends BaseClient {
    this.indexTokenCountMap = {};
    /** @type {(messages: BaseMessage[]) => Promise<void>} */
    this.processMemory;
-    /** @type {Record<number, string> | null} */
-    this.agentIdMap = null;
  }

  /**
@ -288,18 +327,13 @@ class AgentClient extends BaseClient {
    { instructions = null, additional_instructions = null },
    opts,
  ) {
-    let orderedMessages = this.constructor.getMessagesForConversation({
+    const orderedMessages = this.constructor.getMessagesForConversation({
      messages,
      parentMessageId,
      summary: this.shouldSummarize,
+      mapMethod: createMultiAgentMapper(this.options.agent, this.agentConfigs),
    });

-    orderedMessages = applyAgentLabelsToHistory(
-      orderedMessages,
-      this.options.agent,
-      this.agentConfigs,
-    );
-
    let payload;
    /** @type {number | undefined} */
    let promptTokens;
@ -551,10 +585,9 @@ class AgentClient extends BaseClient {
        agent: prelimAgent,
        allowedProviders,
        endpointOption: {
-          endpoint:
-            prelimAgent.id !== Constants.EPHEMERAL_AGENT_ID
-              ? EModelEndpoint.agents
-              : memoryConfig.agent?.provider,
+          endpoint: !isEphemeralAgentId(prelimAgent.id)
+            ? EModelEndpoint.agents
+            : memoryConfig.agent?.provider,
        },
      },
      {
@ -693,9 +726,7 @@ class AgentClient extends BaseClient {
    });

    const completion = filterMalformedContentParts(this.contentParts);
-    const metadata = this.agentIdMap ? { agentIdMap: this.agentIdMap } : undefined;
-
-    return { completion, metadata };
+    return { completion };
  }

  /**
@ -891,12 +922,10 @@ class AgentClient extends BaseClient {
       */
      const runAgents = async (messages) => {
        const agents = [this.options.agent];
-        if (
-          this.agentConfigs &&
-          this.agentConfigs.size > 0 &&
-          ((this.options.agent.edges?.length ?? 0) > 0 ||
-            (await checkCapability(this.options.req, AgentCapabilities.chain)))
-        ) {
+        // Include additional agents when:
+        // - agentConfigs has agents (from addedConvo parallel execution or agent handoffs)
+        // - Agents without incoming edges become start nodes and run in parallel automatically
+        if (this.agentConfigs && this.agentConfigs.size > 0) {
          agents.push(...this.agentConfigs.values());
        }

@ -992,24 +1021,6 @@ class AgentClient extends BaseClient {
          );
        });
      }
-
-      try {
-        /** Capture agent ID map if we have edges or multiple agents */
-        const shouldStoreAgentMap =
-          (this.options.agent.edges?.length ?? 0) > 0 || (this.agentConfigs?.size ?? 0) > 0;
-        if (shouldStoreAgentMap && run?.Graph) {
-          const contentPartAgentMap = run.Graph.getContentPartAgentMap();
-          if (contentPartAgentMap && contentPartAgentMap.size > 0) {
-            this.agentIdMap = Object.fromEntries(contentPartAgentMap);
-            logger.debug('[AgentClient] Captured agent ID map:', {
-              totalParts: this.contentParts.length,
-              mappedParts: Object.keys(this.agentIdMap).length,
-            });
-          }
-        }
-      } catch (error) {
-        logger.error('[AgentClient] Error capturing agent ID map:', error);
-      }
    } catch (err) {
      logger.error(
        '[api/server/controllers/agents/client.js #sendCompletion] Operation aborted',
--- a/api/server/middleware/accessResources/canAccessAgentFromBody.js
+++ b/api/server/middleware/accessResources/canAccessAgentFromBody.js
@ -1,5 +1,10 @@
 const { logger } = require('@librechat/data-schemas');
-const { Constants, isAgentsEndpoint, ResourceType } = require('librechat-data-provider');
+const {
+  Constants,
+  ResourceType,
+  isAgentsEndpoint,
+  isEphemeralAgentId,
+} = require('librechat-data-provider');
 const { canAccessResource } = require('./canAccessResource');
 const { getAgent } = require('~/models/Agent');

@ -13,7 +18,8 @@ const { getAgent } = require('~/models/Agent');
 */
 const resolveAgentIdFromBody = async (agentCustomId) => {
  // Handle ephemeral agents - they don't need permission checks
-  if (agentCustomId === Constants.EPHEMERAL_AGENT_ID) {
+  // Real agent IDs always start with "agent_", so anything else is ephemeral
+  if (isEphemeralAgentId(agentCustomId)) {
    return null; // No permission check needed for ephemeral agents
  }

@ -62,7 +68,8 @@ const canAccessAgentFromBody = (options) => {
      }

      // Skip permission checks for ephemeral agents
-      if (agentId === Constants.EPHEMERAL_AGENT_ID) {
+      // Real agent IDs always start with "agent_", so anything else is ephemeral
+      if (isEphemeralAgentId(agentId)) {
        return next();
      }

--- a/api/server/routes/messages.js
+++ b/api/server/routes/messages.js
@ -1,4 +1,5 @@
 const express = require('express');
+const { v4: uuidv4 } = require('uuid');
 const { logger } = require('@librechat/data-schemas');
 const { ContentTypes } = require('librechat-data-provider');
 const { unescapeLaTeX, countTokens } = require('@librechat/api');
@ -111,6 +112,91 @@ router.get('/', async (req, res) => {
  }
 });

+/**
+ * Creates a new branch message from a specific agent's content within a parallel response message.
+ * Filters the original message's content to only include parts attributed to the specified agentId.
+ * Only available for non-user messages with content attributions.
+ *
+ * @route POST /branch
+ * @param {string} req.body.messageId - The ID of the source message
+ * @param {string} req.body.agentId - The agentId to filter content by
+ * @returns {TMessage} The newly created branch message
+ */
+router.post('/branch', async (req, res) => {
+  try {
+    const { messageId, agentId } = req.body;
+    const userId = req.user.id;
+
+    if (!messageId || !agentId) {
+      return res.status(400).json({ error: 'messageId and agentId are required' });
+    }
+
+    const sourceMessage = await getMessage({ user: userId, messageId });
+    if (!sourceMessage) {
+      return res.status(404).json({ error: 'Source message not found' });
+    }
+
+    if (sourceMessage.isCreatedByUser) {
+      return res.status(400).json({ error: 'Cannot branch from user messages' });
+    }
+
+    if (!Array.isArray(sourceMessage.content)) {
+      return res.status(400).json({ error: 'Message does not have content' });
+    }
+
+    const hasAgentMetadata = sourceMessage.content.some((part) => part?.agentId);
+    if (!hasAgentMetadata) {
+      return res
+        .status(400)
+        .json({ error: 'Message does not have parallel content with attributions' });
+    }
+
+    /** @type {Array<import('librechat-data-provider').TMessageContentParts>} */
+    const filteredContent = [];
+    for (const part of sourceMessage.content) {
+      if (part?.agentId === agentId) {
+        const { agentId: _a, groupId: _g, ...cleanPart } = part;
+        filteredContent.push(cleanPart);
+      }
+    }
+
+    if (filteredContent.length === 0) {
+      return res.status(400).json({ error: 'No content found for the specified agentId' });
+    }
+
+    const newMessageId = uuidv4();
+    /** @type {import('librechat-data-provider').TMessage} */
+    const newMessage = {
+      messageId: newMessageId,
+      conversationId: sourceMessage.conversationId,
+      parentMessageId: sourceMessage.parentMessageId,
+      attachments: sourceMessage.attachments,
+      isCreatedByUser: false,
+      model: sourceMessage.model,
+      endpoint: sourceMessage.endpoint,
+      sender: sourceMessage.sender,
+      iconURL: sourceMessage.iconURL,
+      content: filteredContent,
+      unfinished: false,
+      error: false,
+      user: userId,
+    };
+
+    const savedMessage = await saveMessage(req, newMessage, {
+      context: 'POST /api/messages/branch',
+    });
+
+    if (!savedMessage) {
+      return res.status(500).json({ error: 'Failed to save branch message' });
+    }
+
+    res.status(201).json(savedMessage);
+  } catch (error) {
+    logger.error('Error creating branch message:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
 router.post('/artifact/:messageId', async (req, res) => {
  try {
    const { messageId } = req.params;
--- a/api/server/services/Endpoints/agents/addedConvo.js
+++ b/api/server/services/Endpoints/agents/addedConvo.js
@ -0,0 +1,136 @@
+const { logger } = require('@librechat/data-schemas');
+const { initializeAgent, validateAgentModel } = require('@librechat/api');
+const { loadAddedAgent, setGetAgent, ADDED_AGENT_ID } = require('~/models/loadAddedAgent');
+const { getConvoFiles } = require('~/models/Conversation');
+const { getAgent } = require('~/models/Agent');
+const db = require('~/models');
+
+// Initialize the getAgent dependency
+setGetAgent(getAgent);
+
+/**
+ * Process addedConvo for parallel agent execution.
+ * Creates a parallel agent config from an added conversation.
+ *
+ * When an added agent has no incoming edges, it becomes a start node
+ * and runs in parallel with the primary agent automatically.
+ *
+ * Edge cases handled:
+ * - Primary agent has edges (handoffs): Added agent runs in parallel with primary,
+ *   but doesn't participate in the primary's handoff graph
+ * - Primary agent has agent_ids (legacy chain): Added agent runs in parallel with primary,
+ *   but doesn't participate in the chain
+ * - Primary agent has both: Added agent is independent, runs parallel from start
+ *
+ * @param {Object} params
+ * @param {import('express').Request} params.req
+ * @param {import('express').Response} params.res
+ * @param {Object} params.endpointOption - The endpoint option containing addedConvo
+ * @param {Object} params.modelsConfig - The models configuration
+ * @param {Function} params.logViolation - Function to log violations
+ * @param {Function} params.loadTools - Function to load agent tools
+ * @param {Array} params.requestFiles - Request files
+ * @param {string} params.conversationId - The conversation ID
+ * @param {Set} params.allowedProviders - Set of allowed providers
+ * @param {Map} params.agentConfigs - Map of agent configs to add to
+ * @param {string} params.primaryAgentId - The primary agent ID
+ * @param {Object|undefined} params.userMCPAuthMap - User MCP auth map to merge into
+ * @returns {Promise<{userMCPAuthMap: Object|undefined}>} The updated userMCPAuthMap
+ */
+const processAddedConvo = async ({
+  req,
+  res,
+  endpointOption,
+  modelsConfig,
+  logViolation,
+  loadTools,
+  requestFiles,
+  conversationId,
+  allowedProviders,
+  agentConfigs,
+  primaryAgentId,
+  primaryAgent,
+  userMCPAuthMap,
+}) => {
+  const addedConvo = endpointOption.addedConvo;
+  logger.debug('[processAddedConvo] Called with addedConvo:', {
+    hasAddedConvo: addedConvo != null,
+    addedConvoEndpoint: addedConvo?.endpoint,
+    addedConvoModel: addedConvo?.model,
+    addedConvoAgentId: addedConvo?.agent_id,
+  });
+  if (addedConvo == null) {
+    return { userMCPAuthMap };
+  }
+
+  try {
+    const addedAgent = await loadAddedAgent({ req, conversation: addedConvo, primaryAgent });
+    if (!addedAgent) {
+      return { userMCPAuthMap };
+    }
+
+    const addedValidation = await validateAgentModel({
+      req,
+      res,
+      modelsConfig,
+      logViolation,
+      agent: addedAgent,
+    });
+
+    if (!addedValidation.isValid) {
+      logger.warn(
+        `[processAddedConvo] Added agent validation failed: ${addedValidation.error?.message}`,
+      );
+      return { userMCPAuthMap };
+    }
+
+    const addedConfig = await initializeAgent(
+      {
+        req,
+        res,
+        loadTools,
+        requestFiles,
+        conversationId,
+        agent: addedAgent,
+        endpointOption,
+        allowedProviders,
+      },
+      {
+        getConvoFiles,
+        getFiles: db.getFiles,
+        getUserKey: db.getUserKey,
+        updateFilesUsage: db.updateFilesUsage,
+        getUserKeyValues: db.getUserKeyValues,
+        getToolFilesByIds: db.getToolFilesByIds,
+      },
+    );
+
+    if (userMCPAuthMap != null) {
+      Object.assign(userMCPAuthMap, addedConfig.userMCPAuthMap ?? {});
+    } else {
+      userMCPAuthMap = addedConfig.userMCPAuthMap;
+    }
+
+    const addedAgentId = addedConfig.id || ADDED_AGENT_ID;
+    agentConfigs.set(addedAgentId, addedConfig);
+
+    // No edges needed - agent without incoming edges becomes a start node
+    // and runs in parallel with the primary agent automatically.
+    // This is independent of any edges/agent_ids the primary agent has.
+
+    logger.debug(
+      `[processAddedConvo] Added parallel agent: ${addedAgentId} (primary: ${primaryAgentId}, ` +
+        `primary has edges: ${!!endpointOption.edges}, primary has agent_ids: ${!!endpointOption.agent_ids})`,
+    );
+
+    return { userMCPAuthMap };
+  } catch (err) {
+    logger.error('[processAddedConvo] Error processing addedConvo for parallel agent', err);
+    return { userMCPAuthMap };
+  }
+};
+
+module.exports = {
+  processAddedConvo,
+  ADDED_AGENT_ID,
+};
--- a/api/server/services/Endpoints/agents/build.js
+++ b/api/server/services/Endpoints/agents/build.js
@ -15,6 +15,9 @@ const buildOptions = (req, endpoint, parsedBody, endpointType) => {
    return undefined;
  });

+  /** @type {import('librechat-data-provider').TConversation | undefined} */
+  const addedConvo = req.body?.addedConvo;
+
  return removeNullishValues({
    spec,
    iconURL,
@ -23,6 +26,7 @@ const buildOptions = (req, endpoint, parsedBody, endpointType) => {
    endpointType,
    model_parameters,
    agent: agentPromise,
+    addedConvo,
  });
 };

--- a/api/server/services/Endpoints/agents/initialize.js
+++ b/api/server/services/Endpoints/agents/initialize.js
@ -7,10 +7,10 @@ const {
  createSequentialChainEdges,
 } = require('@librechat/api');
 const {
-  Constants,
  EModelEndpoint,
  isAgentsEndpoint,
  getResponseSender,
+  isEphemeralAgentId,
 } = require('librechat-data-provider');
 const {
  createToolEndCallback,
@ -20,6 +20,7 @@ const { getModelsConfig } = require('~/server/controllers/ModelController');
 const { loadAgentTools } = require('~/server/services/ToolService');
 const AgentClient = require('~/server/controllers/agents/client');
 const { getConvoFiles } = require('~/models/Conversation');
+const { processAddedConvo } = require('./addedConvo');
 const { getAgent } = require('~/models/Agent');
 const { logViolation } = require('~/cache');
 const db = require('~/models');
@ -233,6 +234,33 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
    edges = edges ? edges.concat(chain) : chain;
  }

+  /** Multi-Convo: Process addedConvo for parallel agent execution */
+  const { userMCPAuthMap: updatedMCPAuthMap } = await processAddedConvo({
+    req,
+    res,
+    endpointOption,
+    modelsConfig,
+    logViolation,
+    loadTools,
+    requestFiles,
+    conversationId,
+    allowedProviders,
+    agentConfigs,
+    primaryAgentId: primaryConfig.id,
+    primaryAgent,
+    userMCPAuthMap,
+  });
+
+  if (updatedMCPAuthMap) {
+    userMCPAuthMap = updatedMCPAuthMap;
+  }
+
+  // Ensure edges is an array when we have multiple agents (multi-agent mode)
+  // MultiAgentGraph.categorizeEdges requires edges to be iterable
+  if (agentConfigs.size > 0 && !edges) {
+    edges = [];
+  }
+
  primaryConfig.edges = edges;

  let endpointConfig = appConfig.endpoints?.[primaryConfig.endpoint];
@ -276,10 +304,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
    endpointType: endpointOption.endpointType,
    resendFiles: primaryConfig.resendFiles ?? true,
    maxContextTokens: primaryConfig.maxContextTokens,
-    endpoint:
-      primaryConfig.id === Constants.EPHEMERAL_AGENT_ID
-        ? primaryConfig.endpoint
-        : EModelEndpoint.agents,
+    endpoint: isEphemeralAgentId(primaryConfig.id) ? primaryConfig.endpoint : EModelEndpoint.agents,
  });

  return { client, userMCPAuthMap };
--- a/api/server/services/ToolService.js
+++ b/api/server/services/ToolService.js
@ -9,7 +9,6 @@ const {
 } = require('@librechat/api');
 const {
  Tools,
-  Constants,
  ErrorTypes,
  ContentTypes,
  imageGenTools,
@ -18,6 +17,7 @@ const {
  ImageVisionTool,
  openapiToFunction,
  AgentCapabilities,
+  isEphemeralAgentId,
  validateActionDomain,
  defaultAgentCapabilities,
  validateAndParseOpenAPISpec,
@ -393,7 +393,7 @@ async function loadAgentTools({
  const endpointsConfig = await getEndpointsConfig(req);
  let enabledCapabilities = new Set(endpointsConfig?.[EModelEndpoint.agents]?.capabilities ?? []);
  /** Edge case: use defined/fallback capabilities when the "agents" endpoint is not enabled */
-  if (enabledCapabilities.size === 0 && agent.id === Constants.EPHEMERAL_AGENT_ID) {
+  if (enabledCapabilities.size === 0 && isEphemeralAgentId(agent.id)) {
    enabledCapabilities = new Set(
      appConfig.endpoints?.[EModelEndpoint.agents]?.capabilities ?? defaultAgentCapabilities,
    );