@librechat/agents 3.0.0-rc8 → 3.0.0

package/src/scripts/multi-agent-hybrid-flow.ts

@@ -0,0 +1,310 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import { Run } from '@/run';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import type * as t from '@/types';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Example of hybrid multi-agent system combining handoff and sequential patterns
+ *
+ * Graph structure:
+ * START -> primary_agent -> agent_b -> agent_c -> END
+ *                 |
+ *                 └─> standalone_agent -> END
+ *
+ * Because primary_agent has BOTH handoff and direct edges:
+ * - Uses Command-based routing for exclusive execution
+ * - The primary agent can either:
+ *   1. Handoff to standalone_agent (direct edge to agent_b is cancelled)
+ *   2. OR continue to agent_b -> agent_c (if no handoff occurs)
+ *
+ * This is automatic behavior when an agent has both edge types.
+ */
+async function testHybridMultiAgent() {
+  console.log('Testing Hybrid Multi-Agent System (Sequential + Handoff)...\n');
+
+  // Define agents
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'primary_agent',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1-mini',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are the Primary Agent in a hybrid workflow.
+      
+      You have TWO options:
+      1. If the request requires specialized expertise (complex analysis, deep technical knowledge, etc.), 
+         use the "transfer_to_standalone_agent" tool to hand off to the Standalone Specialist
+      2. If the request is straightforward and can be handled through standard processing,
+         just provide your initial response and it will automatically continue to Agent B
+      
+      Be decisive - either handoff immediately or provide your response.
+      Start your response with "PRIMARY AGENT:" if you're handling it yourself.`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'standalone_agent',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are a Standalone Specialist Agent.
+      You only receive requests that require specialized expertise.
+      
+      Provide a comprehensive, expert-level response to the request.
+      Start your response with "STANDALONE SPECIALIST:"
+      End with "Specialized analysis complete."`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'agent_b',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are Agent B in a sequential workflow.
+      You receive requests that the Primary Agent decided to handle through standard processing.
+      
+      Your job is to:
+      1. Build upon the Primary Agent's initial response
+      2. Add additional processing or analysis (keep it brief, 2-3 sentences)
+      3. Prepare the information for final processing by Agent C
+      
+      Start your response with "AGENT B:" and end with "Passing to final processing..."`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'agent_c',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are Agent C, the final agent in the sequential workflow.
+      
+      Your job is to:
+      1. Review all previous processing from Primary Agent and Agent B
+      2. Provide a final summary or conclusion
+      3. Complete the standard workflow
+      
+      Start your response with "AGENT C:" and end with "Standard workflow complete."`,
+      maxContextTokens: 8000,
+    },
+  ];
+
+  // Define edges combining handoff and direct patterns
+  const edges: t.GraphEdge[] = [
+    // Handoff edge: primary can transfer to standalone
+    {
+      from: 'primary_agent',
+      to: 'standalone_agent',
+      edgeType: 'handoff',
+      description: 'Transfer to standalone specialist for complex requests',
+      prompt: 'Specific instructions for the specialist',
+    },
+    // Direct edge - exclusive with handoffs (automatic when agent has both types)
+    {
+      from: 'primary_agent',
+      to: 'agent_b',
+      edgeType: 'direct',
+      description: 'Continue to Agent B only if no handoff occurs',
+    },
+    // Direct edge: agent_b automatically continues to agent_c
+    {
+      from: 'agent_b',
+      to: 'agent_c',
+      edgeType: 'direct',
+      description: 'Automatic progression from B to C',
+    },
+  ];
+
+  try {
+    // Test with different queries
+    const testQueries = [
+      {
+        query: 'What is the capital of France?',
+        expectedPath: 'sequential',
+        description: 'Simple query - should go through sequential flow',
+      },
+      // {
+      //   query: 'Design a distributed microservices architecture for a real-time trading platform with sub-millisecond latency requirements',
+      //   expectedPath: 'handoff',
+      //   description: 'Complex query - should handoff to specialist',
+      // },
+    ];
+
+    const config = {
+      configurable: {
+        thread_id: 'hybrid-conversation-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    for (const test of testQueries) {
+      console.log(`\n${'='.repeat(70)}`);
+      console.log(`TEST: ${test.description}`);
+      console.log(`QUERY: "${test.query}"`);
+      console.log(`EXPECTED PATH: ${test.expectedPath}`);
+      console.log('='.repeat(70));
+
+      // Reset state
+      conversationHistory.length = 0;
+      conversationHistory.push(new HumanMessage(test.query));
+
+      // Create separate content aggregator for each test
+      const { contentParts, aggregateContent } = createContentAggregator();
+
+      // Track agent progression for this test
+      let currentAgent = '';
+      let handoffOccurred = false;
+
+      // Create custom handlers for this test
+      const customHandlers = {
+        [GraphEvents.TOOL_END]: new ToolEndHandler(),
+        [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+        [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+        [GraphEvents.ON_RUN_STEP]: {
+          handle: (
+            event: GraphEvents.ON_RUN_STEP,
+            data: t.StreamEventData
+          ): void => {
+            const runStepData = data as any;
+            if (runStepData?.name) {
+              currentAgent = runStepData.name;
+              console.log(`\n[${currentAgent}] Processing...`);
+            }
+            aggregateContent({ event, data: data as t.RunStep });
+          },
+        },
+        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+          handle: (
+            event: GraphEvents.ON_RUN_STEP_COMPLETED,
+            data: t.StreamEventData
+          ): void => {
+            const runStepData = data as any;
+            if (runStepData?.name) {
+              console.log(`✓ ${runStepData.name} completed`);
+            }
+            aggregateContent({
+              event,
+              data: data as unknown as { result: t.ToolEndEvent },
+            });
+          },
+        },
+        [GraphEvents.ON_MESSAGE_DELTA]: {
+          handle: (
+            event: GraphEvents.ON_MESSAGE_DELTA,
+            data: t.StreamEventData
+          ): void => {
+            // console.dir(data, { depth: null });
+            aggregateContent({ event, data: data as t.MessageDeltaEvent });
+          },
+        },
+        [GraphEvents.TOOL_START]: {
+          handle: (
+            _event: string,
+            data: t.StreamEventData,
+            metadata?: Record<string, unknown>
+          ): void => {
+            const toolData = data as any;
+            if (toolData?.name?.startsWith(Constants.LC_TRANSFER_TO_)) {
+              const specialist = toolData.name.replace(
+                Constants.LC_TRANSFER_TO_,
+                ''
+              );
+              console.log(`\n🔀 Transferring to ${specialist}...`);
+              handoffOccurred = true;
+            }
+          },
+        },
+      };
+
+      // Create a new run configuration for each test
+      const runConfig: t.RunConfig = {
+        runId: `hybrid-multi-agent-${test.expectedPath}-${Date.now()}`,
+        graphConfig: {
+          type: 'multi-agent',
+          agents,
+          edges,
+        },
+        customHandlers,
+        returnContent: true,
+      };
+
+      // Create and execute a new run for this test
+      const run = await Run.create(runConfig);
+
+      console.log('\nProcessing request...');
+
+      // Process with streaming
+      const inputs = {
+        messages: conversationHistory,
+      };
+
+      const finalContentParts = await run.processStream(inputs, config);
+      const finalMessages = run.getRunMessages();
+
+      if (finalMessages) {
+        conversationHistory.push(...finalMessages);
+      }
+
+      // Show path taken
+      console.log(`\n${'─'.repeat(70)}`);
+      console.log('PATH ANALYSIS:');
+      console.log(`- Query type: ${test.expectedPath}`);
+      console.log(`- Handoff occurred: ${handoffOccurred ? 'YES' : 'NO'}`);
+      console.log(
+        `- Sequential path runs: ${handoffOccurred ? 'NO (exclusive routing)' : 'YES'}`
+      );
+      console.log(
+        `- Result: ${
+          (test.expectedPath === 'handoff' &&
+            handoffOccurred &&
+            !test.query.includes('continue')) ||
+          (test.expectedPath === 'sequential' && !handoffOccurred)
+            ? '✅ CORRECT'
+            : '❌ INCORRECT'
+        }`
+      );
+      console.log('─'.repeat(70));
+
+      // Display the responses
+      const aiMessages = conversationHistory.filter(
+        (msg) => msg._getType() === 'ai'
+      );
+      console.log('\n--- Agent Responses ---');
+      aiMessages.forEach((msg, index) => {
+        console.log(`\nResponse ${index + 1}:`);
+        console.log(msg.content);
+      });
+    }
+
+    // Final summary
+    console.log(`\n${'='.repeat(70)}`);
+    console.log('HYBRID WORKFLOW TEST COMPLETE');
+    console.log('='.repeat(70));
+    console.log('\nThis test demonstrates automatic exclusive routing:');
+    console.log('- When an agent has BOTH handoff and direct edges');
+    console.log('- It uses Command-based routing for exclusive execution');
+    console.log('- Either handoff OR direct edges execute, never both');
+    console.log(
+      '\nThis prevents duplicate processing in delegation scenarios!'
+    );
+  } catch (error) {
+    console.error('Error in hybrid multi-agent test:', error);
+  }
+}
+
+// Run the test
+testHybridMultiAgent();

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

@@ -2,11 +2,12 @@ import { config } from 'dotenv';
 config();
 
 import { HumanMessage, BaseMessage } from '@langchain/core/messages';
-import { Run } from '@/run';
-import { Providers, GraphEvents } from '@/common';
+import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
-import type * as t from '@/types';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
 
 const conversationHistory: BaseMessage[] = [];
 
@@ -35,7 +36,7 @@ async function testParallelMultiAgent() {
       agentId: 'researcher',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are a research coordinator in a multi-agent analysis workflow. Your sole job is to:
@@ -59,7 +60,7 @@ async function testParallelMultiAgent() {
       agentId: 'analyst1',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are a FINANCIAL AND ECONOMIC ANALYST in a parallel analysis workflow. 
@@ -82,7 +83,7 @@ async function testParallelMultiAgent() {
       agentId: 'analyst2',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are a TECHNICAL AND IMPLEMENTATION ANALYST in a parallel analysis workflow.
@@ -106,7 +107,7 @@ async function testParallelMultiAgent() {
       agentId: 'analyst3',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are a MARKET AND INDUSTRY ANALYST in a parallel analysis workflow.
@@ -130,7 +131,7 @@ async function testParallelMultiAgent() {
       agentId: 'summarizer',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are the SYNTHESIS AND SUMMARY EXPERT in a multi-agent workflow.
@@ -332,6 +333,7 @@ IMPORTANT: Each analyst must produce substantive analysis (200+ words), not just
     console.log('\n\nActive agents during execution:', activeAgents.size);
     console.log('Final content parts:', contentParts.length, 'parts');
     console.dir(contentParts, { depth: null });
+    await sleep(3000);
   } catch (error) {
     console.error('Error in parallel multi-agent test:', error);
   }

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

@@ -30,7 +30,7 @@ async function testSequentialMultiAgent() {
       agentId: 'agent_a',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are Agent A, the first agent in a sequential workflow.
@@ -46,7 +46,7 @@ async function testSequentialMultiAgent() {
       agentId: 'agent_b',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are Agent B, the second agent in a sequential workflow.
@@ -62,7 +62,7 @@ async function testSequentialMultiAgent() {
       agentId: 'agent_c',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are Agent C, the final agent in a sequential workflow.

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

@@ -2,11 +2,12 @@ import { config } from 'dotenv';
 config();
 
 import { HumanMessage, BaseMessage } from '@langchain/core/messages';
-import { Run } from '@/run';
-import { Providers, GraphEvents } from '@/common';
+import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
 import { ToolEndHandler, ModelEndHandler } from '@/events';
-import type * as t from '@/types';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
 
 const conversationHistory: BaseMessage[] = [];
 
@@ -353,6 +354,7 @@ async function testSupervisorMultiAgent() {
       console.log(`                 transfer_to_legal_advisor`);
       console.log('─'.repeat(60));
     }
+    await sleep(3000);
   } catch (error) {
     console.error('Error in supervisor multi-agent test:', error);
   }

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

@@ -22,7 +22,7 @@ async function testMultiAgentHandoff() {
       agentId: 'flight_assistant',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions:
@@ -33,7 +33,7 @@ async function testMultiAgentHandoff() {
       agentId: 'hotel_assistant',
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions:

package/src/scripts/search.ts

@@ -77,7 +77,11 @@ async function testStandardStreaming(): Promise<void> {
     graphConfig: {
       type: 'standard',
       llmConfig,
-      tools: [createSearchTool()],
+      tools: [
+        createSearchTool({
+          scraperProvider: 'serper',
+        }),
+      ],
       instructions:
         'You are a friendly AI assistant. Always address the user by their name.',
       // additional_instructions: `The user's name is ${userName} and they are located in ${location}.`,

package/src/scripts/simple.ts

@@ -18,6 +18,7 @@ import {
 import { GraphEvents, Providers, TitleMethod } from '@/common';
 import { getLLMConfig } from '@/utils/llmConfig';
 import { getArgs } from '@/scripts/args';
+import { sleep } from '@/utils/run';
 import { Run } from '@/run';
 
 const conversationHistory: BaseMessage[] = [];
@@ -145,7 +146,9 @@ async function testStandardStreaming(): Promise<void> {
   });
 
   const config = {
+    runId: 'test-simple-script',
     configurable: {
+      user_id: 'user-123',
       thread_id: 'conversation-num-1',
     },
     streamMode: 'values',
@@ -177,6 +180,10 @@ async function testStandardStreaming(): Promise<void> {
     contentParts,
     // titleMethod: TitleMethod.STRUCTURED,
     chainOptions: {
+      configurable: {
+        user_id: 'user-123',
+        thread_id: 'conversation-num-1',
+      },
       callbacks: [
         {
           handleLLMEnd,
@@ -193,6 +200,7 @@ async function testStandardStreaming(): Promise<void> {
   console.log('Collected usage metadata:', collectedUsage);
   console.log('Generated Title:', titleResult);
   console.log('Collected title usage metadata:', collected);
+  await sleep(5000);
 }
 
 process.on('unhandledRejection', (reason, promise) => {

package/src/scripts/test-custom-prompt-key.ts

@@ -24,7 +24,7 @@ async function testCustomPromptKey() {
           agentId: 'supervisor',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Task Supervisor managing different agents:
@@ -41,7 +41,7 @@ async function testCustomPromptKey() {
           agentId: 'researcher',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Research Agent. You receive research queries to investigate.
@@ -52,7 +52,7 @@ async function testCustomPromptKey() {
           agentId: 'designer',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Design Agent. You receive design requirements to implement.
@@ -63,7 +63,7 @@ async function testCustomPromptKey() {
           agentId: 'coder',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Coding Agent. You receive technical specifications to implement.

package/src/scripts/test-handoff-input.ts

@@ -84,7 +84,7 @@ async function testHandoffInput() {
           agentId: 'supervisor',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Task Supervisor. You have access to two specialist agents:
@@ -100,7 +100,7 @@ async function testHandoffInput() {
           agentId: 'analyst',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Data Analyst. Follow the supervisor's instructions carefully.
@@ -111,7 +111,7 @@ async function testHandoffInput() {
           agentId: 'writer',
           provider: Providers.ANTHROPIC,
           clientOptions: {
-            modelName: 'claude-3-5-sonnet-latest',
+            modelName: 'claude-haiku-4-5',
             apiKey: process.env.ANTHROPIC_API_KEY,
           },
           instructions: `You are a Content Writer. Follow the supervisor's instructions carefully.

package/src/scripts/test-multi-agent-list-handoff.ts

@@ -93,7 +93,7 @@ async function testSupervisorListHandoff() {
     const specialistConfig = {
       provider: Providers.ANTHROPIC,
       clientOptions: {
-        modelName: 'claude-3-5-sonnet-latest',
+        modelName: 'claude-haiku-4-5',
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are an Adaptive Specialist. Your agent ID indicates your role:
@@ -114,7 +114,7 @@ async function testSupervisorListHandoff() {
         agentId: 'supervisor',
         provider: Providers.ANTHROPIC,
         clientOptions: {
-          modelName: 'claude-3-5-sonnet-latest',
+          modelName: 'claude-haiku-4-5',
           apiKey: process.env.ANTHROPIC_API_KEY,
         },
         instructions: `You are a Task Supervisor with access to 5 specialist agents:

package/src/scripts/tools.ts

@@ -126,7 +126,10 @@ async function testStandardStreaming(): Promise<void> {
   const inputs = {
     messages: conversationHistory,
   };
-  const finalContentParts = await run.processStream(inputs, config);
+  const finalContentParts = await run.processStream(inputs, config, {
+    indexTokenCountMap: { 0: 35 },
+    maxContextTokens: 89000,
+  });
   const finalMessages = run.getRunMessages();
   if (finalMessages) {
     conversationHistory.push(...finalMessages);