@librechat/agents 3.0.53 → 3.0.55

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-chain.ts

@@ -143,18 +143,49 @@ async function testSequentialAgentChain() {
 
   // Track agent progression
   let currentAgent = '';
+  const startTime = Date.now();
+  let messageCount = 0;
 
-  // Create custom handlers
+  // Create custom handlers with extensive metadata logging
   const customHandlers = {
     [GraphEvents.TOOL_END]: new ToolEndHandler(),
-    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  COMPLETED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  STARTED at ${elapsed}ms`);
+      },
+    },
     [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
     [GraphEvents.ON_RUN_STEP]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
         const runStepData = data as any;
+        console.log('\n====== ON_RUN_STEP ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         if (runStepData?.name) {
           currentAgent = runStepData.name;
           console.log(`\n→ ${currentAgent} is processing...`);
@@ -165,9 +196,15 @@ async function testSequentialAgentChain() {
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_COMPLETED,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
         const runStepData = data as any;
+        console.log('\n====== ON_RUN_STEP_COMPLETED ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         if (runStepData?.name) {
           console.log(`✓ ${runStepData.name} completed`);
         }
@@ -180,16 +217,32 @@ async function testSequentialAgentChain() {
     [GraphEvents.ON_RUN_STEP_DELTA]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== ON_RUN_STEP_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.RunStepDeltaEvent });
       },
     },
     [GraphEvents.ON_MESSAGE_DELTA]: {
       handle: (
         event: GraphEvents.ON_MESSAGE_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        messageCount++;
+        // Only log first few message deltas to avoid spam
+        if (messageCount <= 3) {
+          console.log('\n====== ON_MESSAGE_DELTA ======');
+          console.log('DATA:');
+          console.dir(data, { depth: null });
+          console.log('METADATA:');
+          console.dir(metadata, { depth: null });
+        }
         aggregateContent({ event, data: data as t.MessageDeltaEvent });
       },
     },

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[] = [
@@ -58,7 +59,7 @@ async function testParallelFromStart() {
   const agentTimings: Record<string, { start?: number; end?: number }> = {};
   const startTime = Date.now();
 
-  // Create custom handlers
+  // Create custom handlers with extensive metadata logging
   const customHandlers = {
     [GraphEvents.TOOL_END]: new ToolEndHandler(),
     [GraphEvents.CHAT_MODEL_END]: {
@@ -67,6 +68,8 @@ async function testParallelFromStart() {
         _data: t.StreamEventData,
         metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
         const nodeName = metadata?.langgraph_node as string;
         if (nodeName) {
           const elapsed = Date.now() - startTime;
@@ -82,6 +85,8 @@ async function testParallelFromStart() {
         _data: t.StreamEventData,
         metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
         const nodeName = metadata?.langgraph_node as string;
         if (nodeName) {
           const elapsed = Date.now() - startTime;
@@ -96,8 +101,14 @@ async function testParallelFromStart() {
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_COMPLETED,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== ON_RUN_STEP_COMPLETED ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({
           event,
           data: data as unknown as { result: t.ToolEndEvent },
@@ -107,25 +118,43 @@ async function testParallelFromStart() {
     [GraphEvents.ON_RUN_STEP]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== ON_RUN_STEP ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.RunStep });
       },
     },
     [GraphEvents.ON_RUN_STEP_DELTA]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== ON_RUN_STEP_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.RunStepDeltaEvent });
       },
     },
     [GraphEvents.ON_MESSAGE_DELTA]: {
       handle: (
         event: GraphEvents.ON_MESSAGE_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        // Only log first delta per agent to avoid spam
+        console.log('\n====== ON_MESSAGE_DELTA ======');
+        console.log('DATA:');
         console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.MessageDeltaEvent });
       },
     },
@@ -221,7 +250,11 @@ 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 });
+    console.log('\n=== Content Metadata Map (separate from content) ===');
+    console.dir(Object.fromEntries(contentMetadataMap), { depth: null });
+
     await sleep(3000);
   } catch (error) {
     console.error('Error in parallel-from-start multi-agent test:', error);

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

@@ -200,18 +200,50 @@ async function testParallelMultiAgent() {
 
   // Track which agents are active
   const activeAgents = new Set<string>();
+  const startTime = Date.now();
+  let messageCount = 0;
 
-  // Create custom handlers
+  // Create custom handlers with extensive metadata logging
   const customHandlers = {
     [GraphEvents.TOOL_END]: new ToolEndHandler(),
-    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        const nodeName = metadata?.langgraph_node as string;
+        console.log(`⏱️  [${nodeName || 'unknown'}] COMPLETED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        const nodeName = metadata?.langgraph_node as string;
+        console.log(`⏱️  [${nodeName || 'unknown'}] STARTED at ${elapsed}ms`);
+      },
+    },
     [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_COMPLETED,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
-        console.log('====== ON_RUN_STEP_COMPLETED ======');
+        console.log('\n====== ON_RUN_STEP_COMPLETED ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         const runStepData = data as any;
         if (runStepData?.name) {
           activeAgents.delete(runStepData.name);
@@ -226,9 +258,14 @@ async function testParallelMultiAgent() {
     [GraphEvents.ON_RUN_STEP]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
-        console.log('====== ON_RUN_STEP ======');
+        console.log('\n====== ON_RUN_STEP ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         const runStepData = data as any;
         if (runStepData?.name) {
           activeAgents.add(runStepData.name);
@@ -240,18 +277,32 @@ async function testParallelMultiAgent() {
     [GraphEvents.ON_RUN_STEP_DELTA]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== ON_RUN_STEP_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.RunStepDeltaEvent });
       },
     },
     [GraphEvents.ON_MESSAGE_DELTA]: {
       handle: (
         event: GraphEvents.ON_MESSAGE_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
-        console.log('====== ON_MESSAGE_DELTA ======');
-        console.dir(data, { depth: null });
+        messageCount++;
+        // Only log first few message deltas per agent to avoid spam
+        if (messageCount <= 5) {
+          console.log('\n====== ON_MESSAGE_DELTA ======');
+          console.log('DATA:');
+          console.dir(data, { depth: null });
+          console.log('METADATA:');
+          console.dir(metadata, { depth: null });
+        }
         aggregateContent({ event, data: data as t.MessageDeltaEvent });
       },
     },

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(