@librechat/agents 3.0.52 → 3.0.54

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

@@ -0,0 +1,263 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Example of parallel multi-agent system that starts with parallel execution immediately
+ *
+ * Graph structure:
+ * START -> [analyst1, analyst2] -> END (parallel from start, both run simultaneously)
+ *
+ * This demonstrates getting a parallel stream from the very beginning,
+ * with two agents running simultaneously. Useful for testing how different
+ * models respond to the same input.
+ */
+async function testParallelFromStart() {
+  console.log('Testing Parallel From Start Multi-Agent System...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Define two agents - both have NO incoming edges, so they run in parallel from the start
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'analyst1',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a CREATIVE ANALYST. Analyze the user's query from a creative and innovative perspective. Focus on novel ideas, unconventional approaches, and imaginative possibilities. Keep your response concise (100-150 words). Start with "🎨 CREATIVE:"`,
+    },
+    {
+      agentId: 'analyst2',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a PRACTICAL ANALYST. Analyze the user's query from a logical and practical perspective. Focus on feasibility, metrics, and actionable steps. Keep your response concise (100-150 words). Start with "📊 PRACTICAL:"`,
+    },
+  ];
+
+  // No edges needed - both agents have no incoming edges, so both are start nodes
+  // They will run in parallel and end when both complete
+  const edges: t.GraphEdge[] = [];
+
+  // Track which agents are active and their timing
+  const activeAgents = new Set<string>();
+  const agentTimings: Record<string, { start?: number; end?: number }> = {};
+  const startTime = Date.now();
+
+  // Create custom handlers with extensive metadata logging
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [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 nodeName = metadata?.langgraph_node as string;
+        if (nodeName) {
+          const elapsed = Date.now() - startTime;
+          agentTimings[nodeName] = agentTimings[nodeName] || {};
+          agentTimings[nodeName].end = elapsed;
+          console.log(`⏱️  [${nodeName}] 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 nodeName = metadata?.langgraph_node as string;
+        if (nodeName) {
+          const elapsed = Date.now() - startTime;
+          agentTimings[nodeName] = agentTimings[nodeName] || {};
+          agentTimings[nodeName].start = elapsed;
+          activeAgents.add(nodeName);
+          console.log(`⏱️  [${nodeName}] 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,
+        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 },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        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,
+        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,
+        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 });
+      },
+    },
+  };
+
+  // Create multi-agent run configuration
+  const runConfig: t.RunConfig = {
+    runId: `parallel-start-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    // Create and execute the run
+    const run = await Run.create(runConfig);
+
+    // Debug: Log the graph structure
+    console.log('=== DEBUG: Graph Structure ===');
+    const graph = (run as any).Graph;
+    console.log('Graph exists:', !!graph);
+    if (graph) {
+      console.log('Graph type:', graph.constructor.name);
+      console.log('AgentContexts exists:', !!graph.agentContexts);
+      if (graph.agentContexts) {
+        console.log('AgentContexts size:', graph.agentContexts.size);
+        for (const [agentId, context] of graph.agentContexts) {
+          console.log(`\nAgent: ${agentId}`);
+          console.log(
+            `Tools: ${context.tools?.map((t: any) => t.name || 'unnamed').join(', ') || 'none'}`
+          );
+        }
+      }
+    }
+    console.log('=== END DEBUG ===\n');
+
+    const userMessage = `What are the best approaches to learning a new programming language?`;
+    conversationHistory.push(new HumanMessage(userMessage));
+
+    console.log('Invoking parallel-from-start multi-agent graph...\n');
+    console.log('Both analyst1 and analyst2 should start simultaneously!\n');
+
+    const config = {
+      configurable: {
+        thread_id: 'parallel-start-conversation-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    // Process with streaming
+    const inputs = {
+      messages: conversationHistory,
+    };
+
+    const finalContentParts = await run.processStream(inputs, config);
+    const finalMessages = run.getRunMessages();
+
+    if (finalMessages) {
+      conversationHistory.push(...finalMessages);
+    }
+
+    console.log('\n\n========== TIMING SUMMARY ==========');
+    for (const [agent, timing] of Object.entries(agentTimings)) {
+      const duration =
+        timing.end && timing.start ? timing.end - timing.start : 'N/A';
+      console.log(
+        `${agent}: started=${timing.start}ms, ended=${timing.end}ms, duration=${duration}ms`
+      );
+    }
+
+    // Check if parallel
+    const agents = Object.keys(agentTimings);
+    if (agents.length >= 2) {
+      const [a1, a2] = agents;
+      const t1 = agentTimings[a1];
+      const t2 = agentTimings[a2];
+      if (t1.start && t2.start && t1.end && t2.end) {
+        const overlap = Math.min(t1.end, t2.end) - Math.max(t1.start, t2.start);
+        if (overlap > 0) {
+          console.log(
+            `\n✅ PARALLEL EXECUTION CONFIRMED: ${overlap}ms overlap`
+          );
+        } else {
+          console.log(`\n❌ SEQUENTIAL EXECUTION: no overlap`);
+        }
+      }
+    }
+    console.log('====================================\n');
+
+    console.log('Final content parts:', contentParts.length, 'parts');
+    console.dir(contentParts, { depth: null });
+
+    // groupId on each content part allows frontend to derive boundaries if needed
+
+    await sleep(3000);
+  } catch (error) {
+    console.error('Error in parallel-from-start multi-agent test:', error);
+  }
+}
+
+// Run the test
+testParallelFromStart();

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/parallel-asymmetric-tools-test.ts

@@ -0,0 +1,274 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler } from '@/events';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
+import { Calculator } from '@/tools/Calculator';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Test ASYMMETRIC parallel execution:
+ * - agent1: NO tools (will finish quickly in step 1)
+ * - agent2: HAS tools (will go step 1 → step 2 → step 3)
+ *
+ * This tests whether langgraph_step can still detect parallel execution
+ * when agents have different tool-calling patterns.
+ */
+async function testAsymmetricParallelTools() {
+  console.log(
+    'Testing ASYMMETRIC Parallel Agents (one with tools, one without)...\n'
+  );
+
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Track metadata for analysis
+  const metadataLog: Array<{
+    event: string;
+    langgraph_step: number;
+    langgraph_node: string;
+    timestamp: number;
+  }> = [];
+  const startTime = Date.now();
+
+  // Define two agents - one WITH tools, one WITHOUT
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'simple_agent',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      // NO TOOLS - will complete in single step
+      instructions: `You are a simple assistant. Just answer the question directly in 1-2 sentences. Start with "🗣️ SIMPLE:". Do NOT try to use any tools.`,
+    },
+    {
+      agentId: 'math_agent',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      tools: [new Calculator()],
+      instructions: `You are a MATH SPECIALIST. ALWAYS use the calculator tool to perform calculations, even simple ones. Start your response with "🧮 MATH:". Keep your response concise.`,
+    },
+  ];
+
+  // No edges - both run in parallel from start
+  const edges: t.GraphEdge[] = [];
+
+  const agentTimings: Record<string, { start?: number; end?: number }> = {};
+
+  // Helper to log metadata
+  const logMetadata = (
+    eventName: string,
+    metadata?: Record<string, unknown>
+  ) => {
+    if (metadata) {
+      const entry = {
+        event: eventName,
+        langgraph_step: metadata.langgraph_step as number,
+        langgraph_node: metadata.langgraph_node as string,
+        timestamp: Date.now() - startTime,
+      };
+      metadataLog.push(entry);
+      console.log(
+        `📊 [${entry.timestamp}ms] ${eventName}: step=${entry.langgraph_step}, node=${entry.langgraph_node}`
+      );
+    }
+  };
+
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== TOOL_END ======');
+        logMetadata('TOOL_END', metadata);
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== TOOL_START ======');
+        logMetadata('TOOL_START', metadata);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END ======');
+        logMetadata('CHAT_MODEL_END', metadata);
+        const nodeName = metadata?.langgraph_node as string;
+        if (nodeName) {
+          const elapsed = Date.now() - startTime;
+          agentTimings[nodeName] = agentTimings[nodeName] || {};
+          agentTimings[nodeName].end = elapsed;
+        }
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START ======');
+        logMetadata('CHAT_MODEL_START', metadata);
+        const nodeName = metadata?.langgraph_node as string;
+        if (nodeName) {
+          const elapsed = Date.now() - startTime;
+          agentTimings[nodeName] = agentTimings[nodeName] || {};
+          if (!agentTimings[nodeName].start) {
+            agentTimings[nodeName].start = elapsed;
+          }
+        }
+      },
+    },
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP ======');
+        logMetadata('ON_RUN_STEP', metadata);
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        // Don't log these to reduce noise
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        // Don't log these to reduce noise
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  const runConfig: t.RunConfig = {
+    runId: `asymmetric-parallel-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    const run = await Run.create(runConfig);
+
+    // Ask a question that will trigger only the math agent to use tools
+    const userMessage = `What is 42 * 17?`;
+
+    conversationHistory.push(new HumanMessage(userMessage));
+
+    console.log('User message:', userMessage);
+    console.log('\nExpected behavior:');
+    console.log('  - simple_agent: Step 1 only (no tools)');
+    console.log('  - math_agent: Step 1 → Step 2 (tool) → Step 3 (response)');
+    console.log('\n');
+
+    const config = {
+      configurable: {
+        thread_id: 'asymmetric-test-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    const inputs = {
+      messages: conversationHistory,
+    };
+
+    await run.processStream(inputs, config);
+
+    // Analysis
+    console.log('\n\n========== METADATA ANALYSIS ==========');
+    console.log('\nAll events by step and node:');
+    console.table(metadataLog);
+
+    // Group by step
+    const stepGroups = new Map<number, Map<string, string[]>>();
+    for (const entry of metadataLog) {
+      if (!stepGroups.has(entry.langgraph_step)) {
+        stepGroups.set(entry.langgraph_step, new Map());
+      }
+      const nodeMap = stepGroups.get(entry.langgraph_step)!;
+      if (!nodeMap.has(entry.langgraph_node)) {
+        nodeMap.set(entry.langgraph_node, []);
+      }
+      nodeMap.get(entry.langgraph_node)!.push(entry.event);
+    }
+
+    console.log('\n\n========== STEP BREAKDOWN ==========');
+    for (const [step, nodeMap] of stepGroups) {
+      console.log(`\nStep ${step}:`);
+      for (const [node, events] of nodeMap) {
+        console.log(`  ${node}: ${events.join(', ')}`);
+      }
+      console.log(`  → ${nodeMap.size} unique node(s) at this step`);
+    }
+
+    console.log('\n\n========== PARALLEL DETECTION CHALLENGE ==========');
+    console.log('\nAt which steps can we detect parallel execution?');
+    for (const [step, nodeMap] of stepGroups) {
+      if (nodeMap.size > 1) {
+        console.log(
+          `  ✅ Step ${step}: ${nodeMap.size} agents detected - PARALLEL`
+        );
+      } else {
+        const [nodeName] = nodeMap.keys();
+        console.log(
+          `  ⚠️  Step ${step}: Only 1 agent (${nodeName}) - looks sequential!`
+        );
+      }
+    }
+
+    console.log('\n\n========== KEY INSIGHT ==========');
+    console.log(
+      'If we only look at step 2 or 3, we miss the parallel context!'
+    );
+    console.log(
+      'We need to detect parallelism EARLY (at step 1) and carry that forward.'
+    );
+
+    console.log('\n\nFinal content parts:');
+    console.dir(contentParts, { depth: null });
+
+    await sleep(2000);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+testAsymmetricParallelTools();