@librechat/agents 3.0.54 → 3.0.55

package/src/graphs/MultiAgentGraph.ts

@@ -203,6 +203,14 @@ export class MultiAgentGraph extends StandardGraph {
     return this.agentParallelGroups.get(agentId);
   }
 
+  /**
+   * Override to indicate this is a multi-agent graph.
+   * Enables agentId to be included in RunStep for frontend agent labeling.
+   */
+  protected override isMultiAgentGraph(): boolean {
+    return true;
+  }
+
   /**
    * Override base class method to provide parallel group IDs for run steps.
    */

package/src/messages/format.ts

@@ -14,6 +14,7 @@ import type {
   ExtendedMessageContent,
   MessageContentComplex,
   ReasoningContentText,
+  ContentMetadata,
   ToolCallContent,
   ToolCallPart,
   TPayload,
@@ -626,23 +627,31 @@ export const labelContentByAgent = (
  * @param payload - The array of messages to format.
  * @param indexTokenCountMap - Optional map of message indices to token counts.
  * @param tools - Optional set of tool names that are allowed in the request.
+ * @param options - Optional configuration for agent filtering.
+ * @param options.targetAgentId - If provided, only content parts from this agent will be included.
+ * @param options.contentMetadataMap - Map of content index to metadata (required when targetAgentId is provided).
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
 export const formatAgentMessages = (
   payload: TPayload,
-  indexTokenCountMap?: Record<number, number>,
-  tools?: Set<string>
+  indexTokenCountMap?: Record<number, number | undefined>,
+  tools?: Set<string>,
+  options?: {
+    targetAgentId?: string;
+    contentMetadataMap?: Map<number, ContentMetadata>;
+  }
 ): {
   messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
   indexTokenCountMap?: Record<number, number>;
 } => {
+  const { targetAgentId, contentMetadataMap } = options ?? {};
   const messages: Array<
     HumanMessage | AIMessage | SystemMessage | ToolMessage
   > = [];
   // If indexTokenCountMap is provided, create a new map to track the updated indices
   const updatedIndexTokenCountMap: Record<number, number> = {};
   // Keep track of the mapping from original payload indices to result indices
-  const indexMapping: Record<number, number[]> = {};
+  const indexMapping: Record<number, number[] | undefined> = {};
 
   // Process messages with tool conversion if tools set is provided
   for (let i = 0; i < payload.length; i++) {
@@ -654,6 +663,27 @@ export const formatAgentMessages = (
         { type: ContentTypes.TEXT, [ContentTypes.TEXT]: message.content },
       ];
     }
+
+    // Filter content parts by targetAgentId if provided (only for assistant messages with array content)
+    if (
+      targetAgentId != null &&
+      targetAgentId !== '' &&
+      contentMetadataMap != null &&
+      message.role === 'assistant' &&
+      Array.isArray(message.content)
+    ) {
+      const filteredContent = message.content.filter((_, partIndex) => {
+        const metadata = contentMetadataMap.get(partIndex);
+        return metadata?.agentId === targetAgentId;
+      });
+      // Skip this message entirely if no content parts match the target agent
+      if (filteredContent.length === 0) {
+        indexMapping[i] = [];
+        continue;
+      }
+      message.content = filteredContent;
+    }
+
     if (message.role !== 'assistant') {
       messages.push(
         formatMessage({

package/src/messages/formatAgentMessages.test.ts

@@ -1141,4 +1141,172 @@ describe('formatAgentMessages', () => {
     expect(result.messages[1].name).toBe('search');
     expect(result.messages[1].content).toBe('');
   });
+
+  describe('targetAgentId filtering', () => {
+    it('should filter content parts to only include those from targetAgentId', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Hello' },
+        {
+          role: 'assistant',
+          content: [
+            { type: ContentTypes.TEXT, text: 'Response from agent_a' },
+            { type: ContentTypes.TEXT, text: 'Response from agent_b' },
+            { type: ContentTypes.TEXT, text: 'Another from agent_a' },
+          ],
+        },
+      ];
+
+      const contentMetadataMap = new Map([
+        [0, { agentId: 'agent_a' }],
+        [1, { agentId: 'agent_b' }],
+        [2, { agentId: 'agent_a' }],
+      ]);
+
+      const result = formatAgentMessages(payload, undefined, undefined, {
+        targetAgentId: 'agent_a',
+        contentMetadataMap,
+      });
+
+      // Should have user message + filtered assistant message
+      expect(result.messages).toHaveLength(2);
+      expect(result.messages[0]).toBeInstanceOf(HumanMessage);
+      expect(result.messages[1]).toBeInstanceOf(AIMessage);
+
+      // The AIMessage should only have agent_a's content parts
+      const aiMessage = result.messages[1] as AIMessage;
+      expect(Array.isArray(aiMessage.content)).toBe(true);
+      expect(aiMessage.content as Array<{ text: string }>).toHaveLength(2);
+      expect((aiMessage.content as Array<{ text: string }>)[0].text).toBe(
+        'Response from agent_a'
+      );
+      expect((aiMessage.content as Array<{ text: string }>)[1].text).toBe(
+        'Another from agent_a'
+      );
+    });
+
+    it('should skip assistant message entirely if no content parts match targetAgentId', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Hello' },
+        {
+          role: 'assistant',
+          content: [{ type: ContentTypes.TEXT, text: 'Response from agent_b' }],
+        },
+      ];
+
+      const contentMetadataMap = new Map([[0, { agentId: 'agent_b' }]]);
+
+      const result = formatAgentMessages(payload, undefined, undefined, {
+        targetAgentId: 'agent_a',
+        contentMetadataMap,
+      });
+
+      // Should only have the user message, assistant message skipped
+      expect(result.messages).toHaveLength(1);
+      expect(result.messages[0]).toBeInstanceOf(HumanMessage);
+    });
+
+    it('should not filter when targetAgentId is not provided', () => {
+      const payload: TPayload = [
+        {
+          role: 'assistant',
+          content: [
+            { type: ContentTypes.TEXT, text: 'Response from agent_a' },
+            { type: ContentTypes.TEXT, text: 'Response from agent_b' },
+          ],
+        },
+      ];
+
+      const contentMetadataMap = new Map([
+        [0, { agentId: 'agent_a' }],
+        [1, { agentId: 'agent_b' }],
+      ]);
+
+      // No targetAgentId provided - should include all content
+      const result = formatAgentMessages(payload, undefined, undefined, {
+        contentMetadataMap,
+      });
+
+      expect(result.messages).toHaveLength(1);
+      const aiMessage = result.messages[0] as AIMessage;
+      expect(Array.isArray(aiMessage.content)).toBe(true);
+      expect(aiMessage.content as Array<{ text: string }>).toHaveLength(2);
+    });
+
+    it('should not filter when contentMetadataMap is not provided', () => {
+      const payload: TPayload = [
+        {
+          role: 'assistant',
+          content: [
+            { type: ContentTypes.TEXT, text: 'Response 1' },
+            { type: ContentTypes.TEXT, text: 'Response 2' },
+          ],
+        },
+      ];
+
+      // targetAgentId provided but no contentMetadataMap - should include all content
+      const result = formatAgentMessages(payload, undefined, undefined, {
+        targetAgentId: 'agent_a',
+      });
+
+      expect(result.messages).toHaveLength(1);
+      const aiMessage = result.messages[0] as AIMessage;
+      expect(Array.isArray(aiMessage.content)).toBe(true);
+      expect(aiMessage.content as Array<{ text: string }>).toHaveLength(2);
+    });
+
+    it('should filter content with groupId metadata (parallel execution)', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Analyze this' },
+        {
+          role: 'assistant',
+          content: [
+            { type: ContentTypes.TEXT, text: 'Creative analysis' },
+            { type: ContentTypes.TEXT, text: 'Practical analysis' },
+          ],
+        },
+      ];
+
+      const contentMetadataMap = new Map([
+        [0, { agentId: 'creative_analyst', groupId: 1 }],
+        [1, { agentId: 'practical_analyst', groupId: 1 }],
+      ]);
+
+      const result = formatAgentMessages(payload, undefined, undefined, {
+        targetAgentId: 'creative_analyst',
+        contentMetadataMap,
+      });
+
+      expect(result.messages).toHaveLength(2);
+      const aiMessage = result.messages[1] as AIMessage;
+      expect(Array.isArray(aiMessage.content)).toBe(true);
+      expect(aiMessage.content as Array<{ text: string }>).toHaveLength(1);
+      expect((aiMessage.content as Array<{ text: string }>)[0].text).toBe(
+        'Creative analysis'
+      );
+    });
+
+    it('should not affect non-assistant messages when filtering', () => {
+      const payload: TPayload = [
+        { role: 'user', content: 'Hello from user' },
+        { role: 'system', content: 'System message' },
+        {
+          role: 'assistant',
+          content: [{ type: ContentTypes.TEXT, text: 'From agent_a' }],
+        },
+      ];
+
+      const contentMetadataMap = new Map([[0, { agentId: 'agent_a' }]]);
+
+      const result = formatAgentMessages(payload, undefined, undefined, {
+        targetAgentId: 'agent_a',
+        contentMetadataMap,
+      });
+
+      // All three messages should be present
+      expect(result.messages).toHaveLength(3);
+      expect(result.messages[0]).toBeInstanceOf(HumanMessage);
+      expect(result.messages[1]).toBeInstanceOf(SystemMessage);
+      expect(result.messages[2]).toBeInstanceOf(AIMessage);
+    });
+  });
 });

package/src/scripts/multi-agent-parallel-start.ts

@@ -25,7 +25,8 @@ async function testParallelFromStart() {
   console.log('Testing Parallel From Start Multi-Agent System...\n');
 
   // Set up content aggregator
-  const { contentParts, aggregateContent } = createContentAggregator();
+  const { contentParts, aggregateContent, contentMetadataMap } =
+    createContentAggregator();
 
   // Define two agents - both have NO incoming edges, so they run in parallel from the start
   const agents: t.AgentInputs[] = [
@@ -249,9 +250,10 @@ async function testParallelFromStart() {
     console.log('====================================\n');
 
     console.log('Final content parts:', contentParts.length, 'parts');
+    console.log('\n=== Content Parts (clean, no metadata) ===');
     console.dir(contentParts, { depth: null });
-
-    // groupId on each content part allows frontend to derive boundaries if needed
+    console.log('\n=== Content Metadata Map (separate from content) ===');
+    console.dir(Object.fromEntries(contentMetadataMap), { depth: null });
 
     await sleep(3000);
   } catch (error) {

package/src/scripts/multi-agent-sequence.ts

@@ -22,7 +22,8 @@ async function testSequentialMultiAgent() {
   console.log('Testing Sequential Multi-Agent System (A → B → C)...\n');
 
   // Set up content aggregator
-  const { contentParts, aggregateContent } = createContentAggregator();
+  const { contentParts, aggregateContent, contentMetadataMap } =
+    createContentAggregator();
 
   // Define three simple agents
   const agents: t.AgentInputs[] = [
@@ -194,6 +195,10 @@ async function testSequentialMultiAgent() {
     console.log('\n\n=== Final Output ===');
     console.log('Sequential flow completed successfully!');
     console.log(`Total content parts: ${contentParts.length}`);
+    console.log('\n=== Content Parts (clean, no metadata) ===');
+    console.dir(contentParts, { depth: null });
+    console.log('\n=== Content Metadata Map (separate from content) ===');
+    console.dir(Object.fromEntries(contentMetadataMap), { depth: null });
 
     // Display the sequential responses
     const aiMessages = conversationHistory.filter(

package/src/scripts/single-agent-metadata-test.ts

@@ -20,7 +20,8 @@ async function testSingleAgent() {
   console.log('Testing Single Agent with Metadata Logging...\n');
 
   // Set up content aggregator
-  const { contentParts, aggregateContent } = createContentAggregator();
+  const { contentParts, aggregateContent, contentMetadataMap } =
+    createContentAggregator();
 
   const startTime = Date.now();
 
@@ -179,7 +180,12 @@ async function testSingleAgent() {
 
     console.log('\n\n========== SUMMARY ==========');
     console.log('Final content parts:', contentParts.length, 'parts');
+    console.log('\n=== Content Parts (clean, no metadata) ===');
     console.dir(contentParts, { depth: null });
+    console.log(
+      '\n=== Content Metadata Map (should be empty for single-agent) ==='
+    );
+    console.dir(Object.fromEntries(contentMetadataMap), { depth: null });
     console.log('====================================\n');
 
     await sleep(3000);

package/src/stream.ts

@@ -583,15 +583,6 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         tool_call: newToolCall,
       };
     }
-
-    // Apply agentId and groupId to content part for parallel execution attribution
-    const meta = contentMetaMap.get(index);
-    if (meta?.agentId !== undefined) {
-      (contentParts[index] as t.MessageContentComplex).agentId = meta.agentId;
-    }
-    if (meta?.groupId !== undefined) {
-      (contentParts[index] as t.MessageContentComplex).groupId = meta.groupId;
-    }
   };
 
   const aggregateContent = ({
@@ -610,18 +601,19 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       const runStep = data as t.RunStep;
       stepMap.set(runStep.id, runStep);
 
-      // Track agentId and groupId for this content index
-      const existingMeta = contentMetaMap.get(runStep.index) ?? {};
-      if (runStep.agentId != null && runStep.agentId !== '') {
-        existingMeta.agentId = runStep.agentId;
-      }
-      if (runStep.groupId != null) {
-        existingMeta.groupId = runStep.groupId;
-      }
-      if (
-        (existingMeta.agentId != null && existingMeta.agentId !== '') ||
-        existingMeta.groupId != null
-      ) {
+      // Track agentId (MultiAgentGraph) and groupId (parallel execution) separately
+      // - agentId: present for all MultiAgentGraph runs (enables agent labels in UI)
+      // - groupId: present only for parallel execution (enables column rendering)
+      const hasAgentId = runStep.agentId != null && runStep.agentId !== '';
+      const hasGroupId = runStep.groupId != null;
+      if (hasAgentId || hasGroupId) {
+        const existingMeta = contentMetaMap.get(runStep.index) ?? {};
+        if (hasAgentId) {
+          existingMeta.agentId = runStep.agentId;
+        }
+        if (hasGroupId) {
+          existingMeta.groupId = runStep.groupId;
+        }
         contentMetaMap.set(runStep.index, existingMeta);
       }
 
@@ -735,5 +727,10 @@ export function createContentAggregator(): t.ContentAggregatorResult {
     }
   };
 
-  return { contentParts, aggregateContent, stepMap };
+  return {
+    contentParts,
+    aggregateContent,
+    stepMap,
+    contentMetadataMap: contentMetaMap,
+  };
 }

package/src/types/stream.ts

@@ -343,10 +343,6 @@ export type MessageContentComplex = (
     })
 ) & {
   tool_call_ids?: string[];
-  // Optional agentId for parallel execution attribution
-  agentId?: string;
-  // Optional groupId for parallel group attribution
-  groupId?: number;
 };
 
 export interface TMessage {
@@ -410,8 +406,20 @@ export type ContentAggregator = ({
         result: ToolEndEvent;
       };
 }) => void;
+/**
+ * Metadata for content parts in multi-agent runs.
+ * - agentId: present for all MultiAgentGraph runs (enables agent labels in UI)
+ * - groupId: present only for parallel execution (enables column rendering)
+ */
+export type ContentMetadata = {
+  agentId?: string;
+  groupId?: number;
+};
+
 export type ContentAggregatorResult = {
   stepMap: Map<string, RunStep | undefined>;
   contentParts: Array<MessageContentComplex | undefined>;
+  /** Map of content index to metadata (agentId, groupId). Only populated for MultiAgentGraph runs. */
+  contentMetadataMap: Map<number, ContentMetadata>;
   aggregateContent: ContentAggregator;
 };