@librechat/agents 3.0.0-rc1 → 3.0.0-rc3

package/dist/types/types/graph.d.ts

@@ -28,6 +28,9 @@ export type SystemCallbacks = {
 export type BaseGraphState = {
     messages: BaseMessage[];
 };
+export type MultiAgentGraphState = BaseGraphState & {
+    agentMessages?: BaseMessage[];
+};
 export type IState = BaseGraphState;
 export interface EventHandler {
     handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | {
@@ -46,6 +49,19 @@ export type CompiledStateWorkflow = CompiledStateGraph<StateType<{
 }, {
     messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
 }, StateDefinition>;
+export type CompiledMultiAgentWorkflow = CompiledStateGraph<StateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}>, UpdateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}>, string, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+}, StateDefinition>;
 export type CompiledAgentWorfklow = CompiledStateGraph<{
     messages: BaseMessage[];
 }, {
@@ -185,17 +201,35 @@ export type StandardGraphInput = {
     indexTokenCountMap?: Record<string, number>;
 };
 export type GraphEdge = {
-    /** Use a list for multiple sources */
+    /** Agent ID, use a list for multiple sources */
     from: string | string[];
-    /** Use a list for multiple destinations */
+    /** Agent ID, use a list for multiple destinations */
     to: string | string[];
     description?: string;
     /** Can return boolean or specific destination(s) */
     condition?: (state: BaseGraphState) => boolean | string | string[];
     /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
     edgeType?: 'handoff' | 'direct';
-    /** Optional prompt to add when transitioning through this edge */
-    promptInstructions?: string | ((messages: BaseMessage[]) => string | undefined);
+    /**
+     * For direct edges: Optional prompt to add when transitioning through this edge.
+     * String prompts can include variables like {results} which will be replaced with
+     * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.
+     *
+     * For handoff edges: Description for the input parameter that the handoff tool accepts,
+     * allowing the supervisor to pass specific instructions/context to the transferred agent.
+     */
+    prompt?: string | ((messages: BaseMessage[], runStartIndex: number) => string | undefined);
+    /**
+     * When true, excludes messages from startIndex when adding prompt.
+     * Automatically set to true when {results} variable is used in prompt.
+     */
+    excludeResults?: boolean;
+    /**
+     * For handoff edges: Customizes the parameter name for the handoff input.
+     * Defaults to "instructions" if not specified.
+     * Only applies when prompt is provided for handoff edges.
+     */
+    promptKey?: string;
 };
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];

package/dist/types/types/run.d.ts

@@ -92,9 +92,13 @@ export type MultiAgentGraphConfig = {
     agents: g.AgentInputs[];
     edges: g.GraphEdge[];
 };
+export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type'> & {
+    type?: 'standard';
+    signal?: AbortSignal;
+};
 export type RunConfig = {
     runId: string;
-    graphConfig: LegacyGraphConfig | MultiAgentGraphConfig;
+    graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
     customHandlers?: Record<string, g.EventHandler>;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.00-rc1",
+  "version": "3.0.00-rc3",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -60,6 +60,10 @@
     "multi-agent-parallel": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-parallel.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",
+    "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",
     "script3": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/proto/example_test_anthropic.ts",
     "script4": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/cli4.ts --name 'Jo' --location 'New York, NY'",

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 {
+  ToolMessage,
+  HumanMessage,
+  getBufferString,
+} from '@langchain/core/messages';
+import { ChatPromptTemplate } from '@langchain/core/prompts';
 import {
   END,
   START,
@@ -137,37 +142,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 +200,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 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 +259,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 +281,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 +301,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,18 +335,40 @@ 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
+      /** 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]);
       if (handoffDestinations.size > 0 || directDestinations.size === 0) {
         destinations.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, {
+      /** Wrapper function that handles agentMessages channel */
+      const agentWrapper = async (
+        state: t.MultiAgentGraphState
+      ): Promise<t.MultiAgentGraphState> => {
+        if (state.agentMessages != null && state.agentMessages.length > 0) {
+          /** Temporary state with messages replaced by `agentMessages` */
+          const transformedState: t.MultiAgentGraphState = {
+            ...state,
+            messages: state.agentMessages,
+          };
+          const result = await agentSubgraph.invoke(transformedState);
+          return {
+            ...result,
+            /** Clear agentMessages for next agent */
+            agentMessages: [],
+          };
+        } else {
+          return await agentSubgraph.invoke(state);
+        }
+      };
+
+      /** Wrapped agent as a node with its possible destinations */
+      builder.addNode(agentId, agentWrapper, {
         ends: Array.from(destinations),
       });
     }
@@ -300,7 +380,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 +399,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 = 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 = ChatPromptTemplate.fromTemplate(prompt);
+              const formattedPromptValue = await promptTemplate.invoke({
+                results: resultsString,
+              });
+              promptText = formattedPromptValue.messages[0].content.toString();
+              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,12 +476,12 @@ 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 */
         for (const edge of edges) {
           const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
           for (const source of sources) {

package/src/run.ts

@@ -73,7 +73,7 @@ export class Run<_T extends t.BaseGraphState> {
         this.Graph.handlerRegistry = handlerRegistry;
       }
     } else {
-      // Default to legacy graph for 'standard' or undefined type
+      /** Default to legacy graph for 'standard' or undefined type */
       this.graphRunnable = this.createLegacyGraph(config.graphConfig);
       if (this.Graph) {
         this.Graph.compileOptions =
@@ -86,25 +86,38 @@ export class Run<_T extends t.BaseGraphState> {
   }
 
   private createLegacyGraph(
-    config: t.LegacyGraphConfig
+    config: t.LegacyGraphConfig | t.StandardGraphConfig
   ): t.CompiledStateWorkflow {
-    const {
-      type: _type,
-      llmConfig,
-      signal,
-      tools = [],
-      ...agentInputs
-    } = config;
-    const { provider, ...clientOptions } = llmConfig;
-
-    /** TEMP: Create agent configuration for the single agent */
-    const agentConfig: t.AgentInputs = {
-      ...agentInputs,
-      tools,
-      provider,
-      clientOptions,
-      agentId: 'default',
-    };
+    let agentConfig: t.AgentInputs;
+    let signal: AbortSignal | undefined;
+
+    /** Check if this is a multi-agent style config (has agents array) */
+    if ('agents' in config && Array.isArray(config.agents)) {
+      if (config.agents.length === 0) {
+        throw new Error('At least one agent must be provided');
+      }
+      agentConfig = config.agents[0];
+      signal = config.signal;
+    } else {
+      /** Legacy path: build agent config from llmConfig */
+      const {
+        type: _type,
+        llmConfig,
+        signal: legacySignal,
+        tools = [],
+        ...agentInputs
+      } = config as t.LegacyGraphConfig;
+      const { provider, ...clientOptions } = llmConfig;
+
+      agentConfig = {
+        ...agentInputs,
+        tools,
+        provider,
+        clientOptions,
+        agentId: 'default',
+      };
+      signal = legacySignal;
+    }
 
     const standardGraph = new StandardGraph({
       signal,
@@ -113,10 +126,8 @@ export class Run<_T extends t.BaseGraphState> {
       tokenCounter: this.tokenCounter,
       indexTokenCountMap: this.indexTokenCountMap,
     });
-    // propagate compile options from graph config
-    standardGraph.compileOptions = (
-      config as t.LegacyGraphConfig
-    ).compileOptions;
+    /** Propagate compile options from graph config */
+    standardGraph.compileOptions = config.compileOptions;
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
   }
@@ -145,7 +156,7 @@ export class Run<_T extends t.BaseGraphState> {
   static async create<T extends t.BaseGraphState>(
     config: t.RunConfig
   ): Promise<Run<T>> {
-    // Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not
+    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */
     if (config.indexTokenCountMap && !config.tokenCounter) {
       config.tokenCounter = await createTokenCounter();
     }

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

@@ -167,29 +167,33 @@ async function testParallelMultiAgent() {
       description: 'Aggregate analysis results',
       edgeType: 'direct', // Fan-in is also direct
       // Add prompt when all analysts have provided input
-      promptInstructions: (messages) => {
-        // Check if we have analysis content from all three analysts
-        // Look for the specific headers each analyst uses
-        const aiMessages = messages.filter((msg) => msg._getType() === 'ai');
-        const messageContent = aiMessages.map((msg) => msg.content).join('\n');
-
-        const hasFinancialAnalysis = messageContent.includes(
-          'FINANCIAL ANALYSIS:'
-        );
-        const hasTechnicalAnalysis = messageContent.includes(
-          'TECHNICAL ANALYSIS:'
-        );
-        const hasMarketAnalysis = messageContent.includes('MARKET ANALYSIS:');
-
-        console.log(
-          `Checking for analyses - Financial: ${hasFinancialAnalysis}, Technical: ${hasTechnicalAnalysis}, Market: ${hasMarketAnalysis}`
-        );
-
-        if (hasFinancialAnalysis && hasTechnicalAnalysis && hasMarketAnalysis) {
-          return 'Based on the comprehensive analyses from all three specialist teams above, please synthesize their insights into a cohesive executive summary. Focus on the key findings, common themes, and strategic implications across the financial, technical, and market perspectives.';
-        }
-        return undefined; // No prompt if we haven't received all analyst inputs
-      },
+      // prompt: (messages, runStartIndex) => {
+      //   // Check if we have analysis content from all three analysts
+      //   // Look for the specific headers each analyst uses
+      //   const aiMessages = messages.filter(
+      //     (msg, index) => msg.getType() === 'ai' && index >= runStartIndex
+      //   );
+      //   const messageContent = aiMessages.map((msg) => msg.content).join('\n');
+
+      //   const hasFinancialAnalysis = messageContent.includes(
+      //     'FINANCIAL ANALYSIS:'
+      //   );
+      //   const hasTechnicalAnalysis = messageContent.includes(
+      //     'TECHNICAL ANALYSIS:'
+      //   );
+      //   const hasMarketAnalysis = messageContent.includes('MARKET ANALYSIS:');
+
+      //   console.log(
+      //     `Checking for analyses - Financial: ${hasFinancialAnalysis}, Technical: ${hasTechnicalAnalysis}, Market: ${hasMarketAnalysis}`
+      //   );
+
+      //   if (hasFinancialAnalysis && hasTechnicalAnalysis && hasMarketAnalysis) {
+      //     return 'Based on the comprehensive analyses from all three specialist teams above, please synthesize their insights into a cohesive executive summary. Focus on the key findings, common themes, and strategic implications across the financial, technical, and market perspectives.';
+      //   }
+      //   return undefined; // No prompt if we haven't received all analyst inputs
+      // },
+      prompt:
+        'Based on the comprehensive analyses from all three specialist teams below, please synthesize their insights into a cohesive executive summary. Focus on the key findings, common themes, and strategic implications across the financial, technical, and market perspectives.\n\n{results}',
     },
   ];