@librechat/agents 3.0.0-rc1 → 3.0.0-rc10

package/src/graphs/MultiAgentGraph.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod';
 import { tool } from '@langchain/core/tools';
-import { ToolMessage, HumanMessage } from '@langchain/core/messages';
+import { PromptTemplate } from '@langchain/core/prompts';
+import {
+  ToolMessage,
+  HumanMessage,
+  getBufferString,
+} from '@langchain/core/messages';
 import {
   END,
   START,
@@ -14,10 +19,21 @@ import type { ToolRunnableConfig } from '@langchain/core/tools';
 import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { StandardGraph } from './Graph';
+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[];
@@ -119,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);
-      }
     }
   }
 
@@ -137,37 +145,52 @@ export class MultiAgentGraph extends StandardGraph {
     const tools: t.GenericTool[] = [];
     const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
 
-    // If there's a condition, create a single conditional handoff tool
+    /** If there's a condition, create a single conditional handoff tool */
     if (edge.condition != null) {
       const toolName = 'conditional_transfer';
       const toolDescription =
         edge.description ?? 'Conditionally transfer control based on state';
 
+      /** Check if we have a prompt for handoff input */
+      const hasHandoffInput =
+        edge.prompt != null && typeof edge.prompt === 'string';
+      const handoffInputDescription = hasHandoffInput ? edge.prompt : undefined;
+      const promptKey = edge.promptKey ?? 'instructions';
+
       tools.push(
         tool(
-          async (_, config) => {
+          async (input: Record<string, unknown>, config) => {
             const state = getCurrentTaskInput() as t.BaseGraphState;
             const toolCallId =
               (config as ToolRunnableConfig | undefined)?.toolCall?.id ??
               'unknown';
 
-            // Evaluate condition
+            /** Evaluated condition */
             const result = edge.condition!(state);
             let destination: string;
 
             if (typeof result === 'boolean') {
-              // If true, use first destination; if false, don't transfer
+              /** If true, use first destination; if false, don't transfer */
               if (!result) return null;
               destination = destinations[0];
             } else if (typeof result === 'string') {
               destination = result;
             } else {
-              // Array of destinations - for now, use the first
+              /** Array of destinations - for now, use the first */
               destination = Array.isArray(result) ? result[0] : destinations[0];
             }
 
+            let content = `Conditionally transferred to ${destination}`;
+            if (
+              hasHandoffInput &&
+              promptKey in input &&
+              input[promptKey] != null
+            ) {
+              content += `\n\n${promptKey.charAt(0).toUpperCase() + promptKey.slice(1)}: ${input[promptKey]}`;
+            }
+
             const toolMessage = new ToolMessage({
-              content: `Conditionally transferred to ${destination}`,
+              content,
               name: toolName,
               tool_call_id: toolCallId,
             });
@@ -180,26 +203,51 @@ export class MultiAgentGraph extends StandardGraph {
           },
           {
             name: toolName,
-            schema: z.object({}),
+            schema: hasHandoffInput
+              ? z.object({
+                [promptKey]: z
+                  .string()
+                  .optional()
+                  .describe(handoffInputDescription as string),
+              })
+              : z.object({}),
             description: toolDescription,
           }
         )
       );
     } else {
-      // Create individual tools for each destination
+      /** Create individual tools for each destination */
       for (const destination of destinations) {
-        const toolName = `transfer_to_${destination}`;
+        const toolName = `${Constants.LC_TRANSFER_TO_}${destination}`;
         const toolDescription =
           edge.description ?? `Transfer control to agent '${destination}'`;
 
+        /** Check if we have a prompt for handoff input */
+        const hasHandoffInput =
+          edge.prompt != null && typeof edge.prompt === 'string';
+        const handoffInputDescription = hasHandoffInput
+          ? edge.prompt
+          : undefined;
+        const promptKey = edge.promptKey ?? 'instructions';
+
         tools.push(
           tool(
-            async (_, config) => {
+            async (input: Record<string, unknown>, config) => {
               const toolCallId =
                 (config as ToolRunnableConfig | undefined)?.toolCall?.id ??
                 'unknown';
+
+              let content = `Successfully transferred to ${destination}`;
+              if (
+                hasHandoffInput &&
+                promptKey in input &&
+                input[promptKey] != null
+              ) {
+                content += `\n\n${promptKey.charAt(0).toUpperCase() + promptKey.slice(1)}: ${input[promptKey]}`;
+              }
+
               const toolMessage = new ToolMessage({
-                content: `Successfully transferred to ${destination}`,
+                content,
                 name: toolName,
                 tool_call_id: toolCallId,
               });
@@ -214,7 +262,14 @@ export class MultiAgentGraph extends StandardGraph {
             },
             {
               name: toolName,
-              schema: z.object({}),
+              schema: hasHandoffInput
+                ? z.object({
+                  [promptKey]: z
+                    .string()
+                    .optional()
+                    .describe(handoffInputDescription as string),
+                })
+                : z.object({}),
               description: toolDescription,
             }
           )
@@ -229,14 +284,14 @@ export class MultiAgentGraph extends StandardGraph {
    * Create a complete agent subgraph (similar to createReactAgent)
    */
   private createAgentSubgraph(agentId: string): t.CompiledAgentWorfklow {
-    // This is essentially the same as createAgentNode from StandardGraph
+    /** This is essentially the same as `createAgentNode` from `StandardGraph` */
     return this.createAgentNode(agentId);
   }
 
   /**
    * Create the multi-agent workflow with dynamic handoffs
    */
-  override createWorkflow(): t.CompiledStateWorkflow {
+  override createWorkflow(): t.CompiledMultiAgentWorkflow {
     const StateAnnotation = Annotation.Root({
       messages: Annotation<BaseMessage[]>({
         reducer: (a, b) => {
@@ -249,6 +304,12 @@ export class MultiAgentGraph extends StandardGraph {
         },
         default: () => [],
       }),
+      /** Channel for passing filtered messages to agents when excludeResults is true */
+      agentMessages: Annotation<BaseMessage[]>({
+        /** Replaces state entirely */
+        reducer: (a, b) => b,
+        default: () => [],
+      }),
     });
 
     const builder = new StateGraph(StateAnnotation);
@@ -277,19 +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);
       }
 
-      // Create the agent subgraph (includes agent + tools)
+      /** Agent subgraph (includes agent + tools) */
       const agentSubgraph = this.createAgentSubgraph(agentId);
 
-      // Add the agent as a node with its possible destinations
-      builder.addNode(agentId, agentSubgraph, {
-        ends: Array.from(destinations),
+      /** Wrapper function that handles agentMessages channel and conditional routing */
+      const agentWrapper = async (
+        state: 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,
+          };
+          result = await agentSubgraph.invoke(transformedState);
+          result = {
+            ...result,
+            /** Clear agentMessages for next agent */
+            agentMessages: [],
+          };
+        } else {
+          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(allDestinations),
       });
     }
 
@@ -300,7 +465,8 @@ export class MultiAgentGraph extends StandardGraph {
       builder.addEdge(START, startNode);
     }
 
-    /** Add direct edges for automatic transitions
+    /**
+     * Add direct edges for automatic transitions
      * Group edges by destination to handle fan-in scenarios
      */
     const edgesByDestination = new Map<string, t.GraphEdge[]>();
@@ -318,38 +484,74 @@ export class MultiAgentGraph extends StandardGraph {
     for (const [destination, edges] of edgesByDestination) {
       /** Checks if this is a fan-in scenario with prompt instructions */
       const edgesWithPrompt = edges.filter(
-        (edge) =>
-          edge.promptInstructions != null && edge.promptInstructions !== ''
+        (edge) => edge.prompt != null && edge.prompt !== ''
       );
 
       if (edgesWithPrompt.length > 0) {
-        // Fan-in with prompt: create a single wrapper node for this destination
+        /**
+         * Single wrapper node for destination (Fan-in with prompt)
+         */
         const wrapperNodeId = `fan_in_${destination}_prompt`;
-
-        // Use the first edge's prompt instructions (they should all be the same for fan-in)
-        const promptInstructions = edgesWithPrompt[0].promptInstructions;
+        /**
+         * First edge's `prompt`
+         * (they should all be the same for fan-in)
+         */
+        const prompt = edgesWithPrompt[0].prompt;
+        /**
+         * First edge's `excludeResults` flag
+         * (they should all be the same for fan-in)
+         */
+        const excludeResults = edgesWithPrompt[0].excludeResults;
 
         builder.addNode(wrapperNodeId, async (state: t.BaseGraphState) => {
           let promptText: string | undefined;
-
-          if (typeof promptInstructions === 'function') {
-            promptText = promptInstructions(state.messages);
-          } else {
-            promptText = promptInstructions;
+          let effectiveExcludeResults = excludeResults;
+
+          if (typeof prompt === 'function') {
+            promptText = await prompt(state.messages, this.startIndex);
+          } else if (prompt != null) {
+            if (prompt.includes('{results}')) {
+              const resultsMessages = state.messages.slice(this.startIndex);
+              const resultsString = getBufferString(resultsMessages);
+              const promptTemplate = PromptTemplate.fromTemplate(prompt);
+              const result = await promptTemplate.invoke({
+                results: resultsString,
+              });
+              promptText = result.value;
+              effectiveExcludeResults =
+                excludeResults !== false && promptText !== '';
+            } else {
+              promptText = prompt;
+            }
           }
 
           if (promptText != null && promptText !== '') {
-            // Return state with the prompt message added
+            if (
+              effectiveExcludeResults == null ||
+              effectiveExcludeResults === false
+            ) {
+              return {
+                messages: [new HumanMessage(promptText)],
+              };
+            }
+
+            /** When `excludeResults` is true, use agentMessages channel
+             * to pass filtered messages + prompt to the destination agent
+             */
+            const filteredMessages = state.messages.slice(0, this.startIndex);
             return {
-              messages: [...state.messages, new HumanMessage(promptText)],
+              messages: [new HumanMessage(promptText)],
+              agentMessages: messagesStateReducer(filteredMessages, [
+                new HumanMessage(promptText),
+              ]),
             };
           }
 
-          // No prompt needed, return empty update
+          /** No prompt needed, return empty update */
           return {};
         });
 
-        // Add edges from all sources to the wrapper, then wrapper to destination
+        /** Add edges from all sources to the wrapper, then wrapper to destination */
         for (const edge of edges) {
           const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
           for (const source of sources) {
@@ -359,15 +561,30 @@ export class MultiAgentGraph extends StandardGraph {
           }
         }
 
-        // Single edge from wrapper to destination
+        /** Single edge from wrapper to destination */
         // eslint-disable-next-line @typescript-eslint/ban-ts-comment
         /** @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/llm/openai/index.ts

@@ -30,6 +30,7 @@ import {
   _convertOpenAIResponsesDeltaToBaseMessageChunk,
   type ResponseReturnStreamEvents,
 } from './utils';
+import { sleep } from '@/utils';
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 const iife = <T>(fn: () => T) => fn();
@@ -195,6 +196,17 @@ export class CustomAzureOpenAIClient extends AzureOpenAIClient {
 
 /** @ts-expect-error We are intentionally overriding `getReasoningParams` */
 export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
+  _lc_stream_delay?: number;
+
+  constructor(
+    fields?: t.ChatOpenAICallOptions & {
+      _lc_stream_delay?: number;
+    } & t.OpenAIChatInput['modelKwargs']
+  ) {
+    super(fields);
+    this._lc_stream_delay = fields?._lc_stream_delay;
+  }
+
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
@@ -288,6 +300,9 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
       );
       if (chunk == null) continue;
       yield chunk;
+      if (this._lc_stream_delay != null) {
+        await sleep(this._lc_stream_delay);
+      }
       await runManager?.handleLLMNewToken(
         chunk.text || '',
         undefined,
@@ -376,6 +391,9 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
         generationInfo,
       });
       yield generationChunk;
+      if (this._lc_stream_delay != null) {
+        await sleep(this._lc_stream_delay);
+      }
       await runManager?.handleLLMNewToken(
         generationChunk.text || '',
         newTokenIndices,
@@ -423,6 +441,9 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
         text: '',
       });
       yield generationChunk;
+      if (this._lc_stream_delay != null) {
+        await sleep(this._lc_stream_delay);
+      }
     }
     if (options.signal?.aborted === true) {
       throw new Error('AbortError');
@@ -432,6 +453,13 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
 
 /** @ts-expect-error We are intentionally overriding `getReasoningParams` */
 export class AzureChatOpenAI extends OriginalAzureChatOpenAI {
+  _lc_stream_delay?: number;
+
+  constructor(fields?: t.AzureOpenAIInput & { _lc_stream_delay?: number }) {
+    super(fields);
+    this._lc_stream_delay = fields?._lc_stream_delay;
+  }
+
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
@@ -559,6 +587,9 @@ export class AzureChatOpenAI extends OriginalAzureChatOpenAI {
       );
       if (chunk == null) continue;
       yield chunk;
+      if (this._lc_stream_delay != null) {
+        await sleep(this._lc_stream_delay);
+      }
       await runManager?.handleLLMNewToken(
         chunk.text || '',
         undefined,
@@ -624,13 +655,17 @@ export interface XAIUsageMetadata
 }
 
 export class ChatXAI extends OriginalChatXAI {
+  _lc_stream_delay?: number;
+
   constructor(
     fields?: Partial<ChatXAIInput> & {
       configuration?: { baseURL?: string };
       clientConfig?: { baseURL?: string };
+      _lc_stream_delay?: number;
     }
   ) {
     super(fields);
+    this._lc_stream_delay = fields?._lc_stream_delay;
     const customBaseURL =
       fields?.configuration?.baseURL ?? fields?.clientConfig?.baseURL;
     if (customBaseURL != null && customBaseURL) {
@@ -759,6 +794,9 @@ export class ChatXAI extends OriginalChatXAI {
         generationInfo,
       });
       yield generationChunk;
+      if (this._lc_stream_delay != null) {
+        await sleep(this._lc_stream_delay);
+      }
       await runManager?.handleLLMNewToken(
         generationChunk.text || '',
         newTokenIndices,
@@ -832,6 +870,9 @@ export class ChatXAI extends OriginalChatXAI {
         text: '',
       });
       yield generationChunk;
+      if (this._lc_stream_delay != null) {
+        await sleep(this._lc_stream_delay);
+      }
     }
     if (options.signal?.aborted === true) {
       throw new Error('AbortError');