@librechat/agents 3.0.0-rc7 → 3.0.0-rc9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.00-rc7",
+  "version": "3.0.00-rc9",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -57,11 +57,14 @@
     "abort": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/abort.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "start:cli2": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli2.ts --provider 'anthropic' --name 'Jo' --location 'New York, NY'",
     "multi-agent-test": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-test.ts",
+    "test-tools-before-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-tools-before-handoff.ts",
     "multi-agent-parallel": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-parallel.ts",
+    "multi-agent-chain": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-chain.ts",
     "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
     "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
     "multi-agent-supervisor": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-supervisor.ts",
     "multi-agent-list-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-multi-agent-list-handoff.ts",
+    "multi-agent-hybrid-flow": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-hybrid-flow.ts",
     "test-handoff-input": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-input.ts",
     "test-custom-prompt-key": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-custom-prompt-key.ts",
     "script2": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/proto/example_test.ts",
@@ -115,6 +118,7 @@
   "devDependencies": {
     "@anthropic-ai/vertex-sdk": "^0.12.0",
     "@eslint/compat": "^1.2.7",
+    "@langchain/tavily": "^0.1.5",
     "@rollup/plugin-alias": "^5.1.0",
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-json": "^6.1.0",

package/src/graphs/Graph.ts

@@ -380,7 +380,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     currentTools?: t.GraphTools;
     currentToolMap?: t.ToolMap;
   }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState> {
-    // return new ToolNode<t.BaseGraphState>(this.tools);
     return new CustomToolNode<t.BaseGraphState>({
       tools: (currentTools as t.GenericTool[] | undefined) ?? [],
       toolMap: currentToolMap,

package/src/graphs/MultiAgentGraph.ts

@@ -23,7 +23,17 @@ import { Constants } from '@/common';
 
 /**
  * MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
- * with handoffs, fan-in/fan-out, and other composable patterns
+ * with handoffs, fan-in/fan-out, and other composable patterns.
+ *
+ * Key behavior:
+ * - Agents with ONLY handoff edges: Can dynamically route to any handoff destination
+ * - Agents with ONLY direct edges: Always follow their direct edges
+ * - Agents with BOTH: Use Command for exclusive routing (handoff OR direct, not both)
+ *   - If handoff occurs: Only the handoff destination executes
+ *   - If no handoff: Direct edges execute (potentially in parallel)
+ *
+ * This enables the common pattern where an agent either delegates (handoff)
+ * OR continues its workflow (direct edges), but not both simultaneously.
  */
 export class MultiAgentGraph extends StandardGraph {
   private edges: t.GraphEdge[];
@@ -125,14 +135,6 @@ export class MultiAgentGraph extends StandardGraph {
         agentContext.tools = [];
       }
       agentContext.tools.push(...handoffTools);
-
-      // Update tool map
-      for (const tool of handoffTools) {
-        if (!agentContext.toolMap) {
-          agentContext.toolMap = new Map();
-        }
-        agentContext.toolMap.set(tool.name, tool);
-      }
     }
   }
 
@@ -336,41 +338,123 @@ export class MultiAgentGraph extends StandardGraph {
         }
       }
 
-      /** If agent has handoff destinations, add END to possible ends
-       * If agent only has direct destinations, it naturally ends without explicit END
-       */
-      const destinations = new Set([...handoffDestinations]);
+      /** Check if this agent has BOTH handoff and direct edges */
+      const hasHandoffEdges = handoffDestinations.size > 0;
+      const hasDirectEdges = directDestinations.size > 0;
+      const needsCommandRouting = hasHandoffEdges && hasDirectEdges;
+
+      /** Collect all possible destinations for this agent */
+      const allDestinations = new Set([
+        ...handoffDestinations,
+        ...directDestinations,
+      ]);
       if (handoffDestinations.size > 0 || directDestinations.size === 0) {
-        destinations.add(END);
+        allDestinations.add(END);
       }
 
       /** Agent subgraph (includes agent + tools) */
       const agentSubgraph = this.createAgentSubgraph(agentId);
 
-      /** Wrapper function that handles agentMessages channel */
+      /** Wrapper function that handles agentMessages channel and conditional routing */
       const agentWrapper = async (
         state: t.MultiAgentGraphState
-      ): Promise<t.MultiAgentGraphState> => {
+      ): Promise<t.MultiAgentGraphState | Command> => {
+        let result: t.MultiAgentGraphState;
+
         if (state.agentMessages != null && state.agentMessages.length > 0) {
+          /**
+           * When using agentMessages (excludeResults=true), we need to update
+           * the token map to account for the new prompt message
+           */
+          const agentContext = this.agentContexts.get(agentId);
+          if (agentContext && agentContext.tokenCounter) {
+            // The agentMessages contains:
+            // 1. Filtered messages (0 to startIndex) - already have token counts
+            // 2. New prompt message - needs token counting
+
+            const freshTokenMap: Record<string, number> = {};
+
+            // Copy existing token counts for filtered messages (0 to startIndex)
+            for (let i = 0; i < this.startIndex; i++) {
+              const tokenCount = agentContext.indexTokenCountMap[i];
+              if (tokenCount !== undefined) {
+                freshTokenMap[i] = tokenCount;
+              }
+            }
+
+            // Calculate tokens only for the new prompt message (last message)
+            const promptMessageIndex = state.agentMessages.length - 1;
+            if (promptMessageIndex >= this.startIndex) {
+              const promptMessage = state.agentMessages[promptMessageIndex];
+              freshTokenMap[promptMessageIndex] =
+                agentContext.tokenCounter(promptMessage);
+            }
+
+            // Update the agent's token map with instructions added
+            agentContext.updateTokenMapWithInstructions(freshTokenMap);
+          }
+
           /** Temporary state with messages replaced by `agentMessages` */
           const transformedState: t.MultiAgentGraphState = {
             ...state,
             messages: state.agentMessages,
           };
-          const result = await agentSubgraph.invoke(transformedState);
-          return {
+          result = await agentSubgraph.invoke(transformedState);
+          result = {
             ...result,
             /** Clear agentMessages for next agent */
             agentMessages: [],
           };
         } else {
-          return await agentSubgraph.invoke(state);
+          result = await agentSubgraph.invoke(state);
+        }
+
+        /** If agent has both handoff and direct edges, use Command for exclusive routing */
+        if (needsCommandRouting) {
+          /** Check if a handoff occurred */
+          const lastMessage = result.messages[
+            result.messages.length - 1
+          ] as BaseMessage | null;
+          if (
+            lastMessage != null &&
+            lastMessage.getType() === 'tool' &&
+            typeof lastMessage.name === 'string' &&
+            lastMessage.name.startsWith(Constants.LC_TRANSFER_TO_)
+          ) {
+            /** Handoff occurred - extract destination and navigate there exclusively */
+            const handoffDest = lastMessage.name.replace(
+              Constants.LC_TRANSFER_TO_,
+              ''
+            );
+            return new Command({
+              update: result,
+              goto: handoffDest,
+            });
+          } else {
+            /** No handoff - proceed with direct edges */
+            const directDests = Array.from(directDestinations);
+            if (directDests.length === 1) {
+              return new Command({
+                update: result,
+                goto: directDests[0],
+              });
+            } else if (directDests.length > 1) {
+              /** Multiple direct destinations - they'll run in parallel */
+              return new Command({
+                update: result,
+                goto: directDests,
+              });
+            }
+          }
         }
+
+        /** No special routing needed - return state normally */
+        return result;
       };
 
       /** Wrapped agent as a node with its possible destinations */
       builder.addNode(agentId, agentWrapper, {
-        ends: Array.from(destinations),
+        ends: Array.from(allDestinations),
       });
     }
 
@@ -482,10 +566,25 @@ export class MultiAgentGraph extends StandardGraph {
         /** @ts-ignore */
         builder.addEdge(wrapperNodeId, destination);
       } else {
-        /** No prompt instructions, add direct edges */
+        /** No prompt instructions, add direct edges (skip if source uses Command routing) */
         for (const edge of edges) {
           const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
           for (const source of sources) {
+            /** Check if this source node has both handoff and direct edges */
+            const sourceHandoffEdges = this.handoffEdges.filter((e) => {
+              const eSources = Array.isArray(e.from) ? e.from : [e.from];
+              return eSources.includes(source);
+            });
+            const sourceDirectEdges = this.directEdges.filter((e) => {
+              const eSources = Array.isArray(e.from) ? e.from : [e.from];
+              return eSources.includes(source);
+            });
+
+            /** Skip adding edge if source uses Command routing (has both types) */
+            if (sourceHandoffEdges.length > 0 && sourceDirectEdges.length > 0) {
+              continue;
+            }
+
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment
             /** @ts-ignore */
             builder.addEdge(source, destination);

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

@@ -0,0 +1,278 @@
+import { config } from 'dotenv';
+config();
+
+import {
+  HumanMessage,
+  BaseMessage,
+  getBufferString,
+} from '@langchain/core/messages';
+import { Run } from '@/run';
+import { Providers, GraphEvents } from '@/common';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import type * as t from '@/types';
+
+/**
+ * Helper function to create sequential chain edges with buffer string prompts
+ *
+ * @param agentIds - Array of agent IDs in order of execution
+ * @returns Array of edges configured for sequential chain with buffer prompts
+ */
+function createSequentialChainEdges(agentIds: string[]): t.GraphEdge[] {
+  const edges: t.GraphEdge[] = [];
+
+  for (let i = 0; i < agentIds.length - 1; i++) {
+    const fromAgent = agentIds[i];
+    const toAgent = agentIds[i + 1];
+
+    edges.push({
+      from: fromAgent,
+      to: toAgent,
+      edgeType: 'direct',
+      // Use a prompt function to create the buffer string from all previous results
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        // Get only the messages from this run (after startIndex)
+        const runMessages = messages.slice(startIndex);
+
+        // Create buffer string from run messages
+        const bufferString = getBufferString(runMessages);
+
+        // Format the prompt for the next agent
+        return `Based on the following conversation and analysis from previous agents, please provide your insights:\n\n${bufferString}\n\nPlease add your specific expertise and perspective to this discussion.`;
+      },
+      // Critical: exclude previous results so only the prompt is passed
+      excludeResults: true,
+      description: `Sequential chain from ${fromAgent} to ${toAgent}`,
+    });
+  }
+
+  return edges;
+}
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Example of sequential agent chain mimicking the old chain behavior
+ *
+ * Graph structure:
+ * START -> researcher -> analyst -> reviewer -> summarizer -> END
+ *
+ * Each agent receives a buffer string of all previous results
+ */
+async function testSequentialAgentChain() {
+  console.log('Testing Sequential Agent Chain (Old Chain Pattern)...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Define four agents with specific roles
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'researcher',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a Research Agent specializing in gathering initial information.
+      Your role is to:
+      1. Identify key aspects of the user's query
+      2. List important factors to consider
+      3. Provide initial research findings
+      
+      Format your response with clear sections and bullet points.
+      Start with "RESEARCH FINDINGS:" and be thorough but concise.`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'analyst',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are an Analysis Agent that builds upon research findings.
+      Your role is to:
+      1. Analyze the research provided by the previous agent
+      2. Identify patterns, risks, and opportunities
+      3. Provide deeper analytical insights
+      
+      Start with "ANALYSIS:" and structure your response with clear categories.
+      Reference specific points from the research when relevant.`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'reviewer',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a Critical Review Agent that evaluates the work done so far.
+      Your role is to:
+      1. Review the research and analysis from previous agents
+      2. Identify any gaps or areas that need more attention
+      3. Suggest improvements or additional considerations
+      
+      Start with "CRITICAL REVIEW:" and be constructive in your feedback.
+      Highlight both strengths and areas for improvement.`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'summarizer',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a Summary Agent that creates the final comprehensive output.
+      Your role is to:
+      1. Synthesize all insights from the researcher, analyst, and reviewer
+      2. Create a cohesive, actionable summary
+      3. Provide clear recommendations or conclusions
+      
+      Start with "EXECUTIVE SUMMARY:" followed by key sections.
+      End with "KEY RECOMMENDATIONS:" or "CONCLUSIONS:" as appropriate.`,
+      maxContextTokens: 8000,
+    },
+  ];
+
+  // Create sequential chain edges using our helper function
+  const agentIds = agents.map((a) => a.agentId);
+  const edges = createSequentialChainEdges(agentIds);
+
+  // Track agent progression
+  let currentAgent = '';
+
+  // Create custom handlers
+  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} is 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_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  // Create multi-agent run configuration
+  const runConfig: t.RunConfig = {
+    runId: `sequential-chain-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    // Create and execute the run
+    const run = await Run.create(runConfig);
+
+    // Test with a complex question that benefits from multiple perspectives
+    const userMessage =
+      'I want to launch a new mobile app for personal finance management. What should I consider?';
+    conversationHistory.push(new HumanMessage(userMessage));
+
+    console.log(`User: "${userMessage}"\n`);
+    console.log('Starting sequential agent chain...\n');
+
+    const config = {
+      configurable: {
+        thread_id: 'sequential-chain-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=== Final Output ===');
+    console.log('Sequential chain completed successfully!');
+    console.log(`Total content parts: ${contentParts.length}`);
+
+    // Display the buffer accumulation
+    console.log('\n=== Agent Outputs (Buffer Accumulation) ===');
+
+    const aiMessages = conversationHistory.filter(
+      (msg) => msg._getType() === 'ai'
+    );
+
+    aiMessages.forEach((msg, index) => {
+      console.log(`\n--- Agent ${index + 1}: ${agentIds[index]} ---`);
+      console.log(msg.content);
+
+      // Show buffer preview for next agent (except last)
+      if (index < aiMessages.length - 1) {
+        const bufferSoFar = getBufferString(aiMessages.slice(0, index + 1));
+        console.log(
+          `\n[Buffer passed to ${agentIds[index + 1]}]: ${bufferSoFar.slice(0, 150)}...`
+        );
+      }
+    });
+
+    // Demonstrate that each agent built upon previous results
+    console.log('\n=== Chain Analysis ===');
+    console.log('1. Researcher provided initial findings');
+    console.log('2. Analyst built upon research with deeper insights');
+    console.log('3. Reviewer critiqued and identified gaps');
+    console.log('4. Summarizer synthesized everything into actionable output');
+  } catch (error) {
+    console.error('Error in sequential agent chain test:', error);
+  }
+}
+
+// Run the test
+testSequentialAgentChain();