@librechat/agents 3.0.60 → 3.0.62

package/src/graphs/MultiAgentGraph.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { tool } from '@langchain/core/tools';
 import { PromptTemplate } from '@langchain/core/prompts';
 import {
+  AIMessage,
   ToolMessage,
   HumanMessage,
   getBufferString,
@@ -15,12 +16,15 @@ import {
   getCurrentTaskInput,
   messagesStateReducer,
 } from '@langchain/langgraph';
+import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
 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';
 
+/** Pattern to extract instructions from transfer ToolMessage content */
+const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
+
 /**
  * MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
  * with handoffs, fan-in/fan-out, and other composable patterns.
@@ -312,6 +316,10 @@ export class MultiAgentGraph extends StandardGraph {
               content,
               name: toolName,
               tool_call_id: toolCallId,
+              additional_kwargs: {
+                /** Store destination for programmatic access in handoff detection */
+                handoff_destination: destination,
+              },
             });
 
             return new Command({
@@ -407,6 +415,112 @@ export class MultiAgentGraph extends StandardGraph {
     return this.createAgentNode(agentId);
   }
 
+  /**
+   * Detects if the current agent is receiving a handoff and processes the messages accordingly.
+   * Returns filtered messages with the transfer tool call/message removed, plus any instructions
+   * extracted from the transfer to be injected as a HumanMessage preamble.
+   *
+   * @param messages - Current state messages
+   * @param agentId - The agent ID to check for handoff reception
+   * @returns Object with filtered messages and extracted instructions, or null if not a handoff
+   */
+  private processHandoffReception(
+    messages: BaseMessage[],
+    agentId: string
+  ): { filteredMessages: BaseMessage[]; instructions: string | null } | null {
+    if (messages.length === 0) return null;
+
+    const lastMessage = messages[messages.length - 1];
+
+    /** Check if last message is a transfer ToolMessage targeting this agent */
+    if (lastMessage.getType() !== 'tool') return null;
+
+    const toolMessage = lastMessage as ToolMessage;
+    const toolName = toolMessage.name;
+
+    if (typeof toolName !== 'string') return null;
+
+    /** Check for standard transfer pattern */
+    const isTransferMessage = toolName.startsWith(Constants.LC_TRANSFER_TO_);
+    const isConditionalTransfer = toolName === 'conditional_transfer';
+
+    if (!isTransferMessage && !isConditionalTransfer) return null;
+
+    /** Extract destination from tool name or additional_kwargs */
+    let destinationAgent: string | null = null;
+
+    if (isTransferMessage) {
+      destinationAgent = toolName.replace(Constants.LC_TRANSFER_TO_, '');
+    } else if (isConditionalTransfer) {
+      /** For conditional transfers, read destination from additional_kwargs */
+      const handoffDest = toolMessage.additional_kwargs.handoff_destination;
+      destinationAgent = typeof handoffDest === 'string' ? handoffDest : null;
+    }
+
+    /** Verify this agent is the intended destination */
+    if (destinationAgent !== agentId) return null;
+
+    /** Extract instructions from the ToolMessage content */
+    const contentStr =
+      typeof toolMessage.content === 'string'
+        ? toolMessage.content
+        : JSON.stringify(toolMessage.content);
+
+    const instructionsMatch = contentStr.match(HANDOFF_INSTRUCTIONS_PATTERN);
+    const instructions = instructionsMatch?.[1]?.trim() ?? null;
+
+    /** Get the tool_call_id to find and filter the AI message's tool call */
+    const toolCallId = toolMessage.tool_call_id;
+
+    /** Filter out the transfer messages */
+    const filteredMessages: BaseMessage[] = [];
+
+    for (let i = 0; i < messages.length - 1; i++) {
+      /** Exclude the last message (ToolMessage) by iterating to length - 1 */
+      const msg = messages[i];
+      const msgType = msg.getType();
+
+      if (msgType === 'ai') {
+        /** Check if this AI message contains the transfer tool call */
+        const aiMsg = msg as AIMessage | AIMessageChunk;
+        const toolCalls = aiMsg.tool_calls;
+
+        if (toolCalls && toolCalls.length > 0) {
+          const transferCallIndex = toolCalls.findIndex(
+            (tc) => tc.id === toolCallId
+          );
+
+          if (transferCallIndex >= 0) {
+            /** This AI message has the transfer tool call - filter it out */
+            const remainingToolCalls = toolCalls.filter(
+              (tc) => tc.id !== toolCallId
+            );
+
+            if (
+              remainingToolCalls.length > 0 ||
+              (typeof aiMsg.content === 'string' && aiMsg.content.trim())
+            ) {
+              /** Keep the message but without the transfer tool call */
+              const filteredAiMsg = new AIMessage({
+                content: aiMsg.content,
+                tool_calls: remainingToolCalls,
+                id: aiMsg.id,
+              });
+              filteredMessages.push(filteredAiMsg);
+            }
+            /** If no remaining content or tool calls, skip this message entirely */
+            continue;
+          }
+        }
+      }
+
+      /** Keep all other messages */
+      filteredMessages.push(msg);
+    }
+
+    return { filteredMessages, instructions };
+  }
+
   /**
    * Create the multi-agent workflow with dynamic handoffs
    */
@@ -474,26 +588,85 @@ export class MultiAgentGraph extends StandardGraph {
       /** Agent subgraph (includes agent + tools) */
       const agentSubgraph = this.createAgentSubgraph(agentId);
 
-      /** Wrapper function that handles agentMessages channel and conditional routing */
+      /** Wrapper function that handles agentMessages channel, handoff reception, 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) {
+        /**
+         * Check if this agent is receiving a handoff.
+         * If so, filter out the transfer messages and inject instructions as preamble.
+         * This prevents the receiving agent from seeing the transfer as "completed work"
+         * and prematurely producing an end token.
+         */
+        const handoffContext = this.processHandoffReception(
+          state.messages,
+          agentId
+        );
+
+        if (handoffContext !== null) {
+          const { filteredMessages, instructions } = handoffContext;
+
+          /** Build messages for the receiving agent */
+          let messagesForAgent = filteredMessages;
+
+          /** If there are instructions, inject them as a HumanMessage to ground the agent */
+          const hasInstructions = instructions !== null && instructions !== '';
+          if (hasInstructions) {
+            messagesForAgent = [
+              ...filteredMessages,
+              new HumanMessage(instructions),
+            ];
+          }
+
+          /** Update token map if we have a token counter */
+          const agentContext = this.agentContexts.get(agentId);
+          if (agentContext?.tokenCounter && hasInstructions) {
+            const freshTokenMap: Record<string, number> = {};
+            for (
+              let i = 0;
+              i < Math.min(filteredMessages.length, this.startIndex);
+              i++
+            ) {
+              const tokenCount = agentContext.indexTokenCountMap[i];
+              if (tokenCount !== undefined) {
+                freshTokenMap[i] = tokenCount;
+              }
+            }
+            /** Add tokens for the instructions message */
+            const instructionsMsg = new HumanMessage(instructions);
+            freshTokenMap[messagesForAgent.length - 1] =
+              agentContext.tokenCounter(instructionsMsg);
+            agentContext.updateTokenMapWithInstructions(freshTokenMap);
+          }
+
+          const transformedState: t.MultiAgentGraphState = {
+            ...state,
+            messages: messagesForAgent,
+          };
+          result = await agentSubgraph.invoke(transformedState);
+          result = {
+            ...result,
+            agentMessages: [],
+          };
+        } else 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
-
+            /** 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)
+            /** 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) {
@@ -501,7 +674,7 @@ export class MultiAgentGraph extends StandardGraph {
               }
             }
 
-            // Calculate tokens only for the new prompt message (last message)
+            /** 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];
@@ -509,7 +682,7 @@ export class MultiAgentGraph extends StandardGraph {
                 agentContext.tokenCounter(promptMessage);
             }
 
-            // Update the agent's token map with instructions added
+            /** Update the agent's token map with instructions added */
             agentContext.updateTokenMapWithInstructions(freshTokenMap);
           }
 

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

@@ -210,6 +210,7 @@ async function testConditionalMultiAgent() {
       console.log(`\n\nExpert used: ${selectedExpert}`);
       console.log('Content parts:', contentParts.length);
       console.log('---');
+      console.dir(contentParts, { depth: null });
     }
   } catch (error) {
     console.error('Error in conditional multi-agent test:', error);

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

@@ -353,6 +353,7 @@ async function testSupervisorMultiAgent() {
       );
       console.log(`                 transfer_to_legal_advisor`);
       console.log('─'.repeat(60));
+      console.dir(contentParts, { depth: null });
     }
     await sleep(3000);
   } catch (error) {

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

@@ -0,0 +1,275 @@
+/**
+ * Test script for multi-turn handoff behavior.
+ *
+ * This tests the fix for the issue where receiving agents would see transfer messages
+ * and prematurely produce end tokens, thinking the work was already done.
+ *
+ * The fix:
+ * 1. Filters out transfer tool calls and ToolMessages from the receiving agent's context
+ * 2. Injects any passthrough instructions as a HumanMessage to ground the receiving agent
+ */
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { GraphEvents, Providers } from '@/common';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Test multi-turn handoff between a coordinator and a specialist
+ */
+async function testHandoffPreamble(): Promise<void> {
+  console.log('='.repeat(60));
+  console.log('Testing Multi-Turn Handoff with Preamble Injection');
+  console.log('='.repeat(60));
+  console.log('\nThis test verifies that:');
+  console.log('1. Transfer messages are filtered from receiving agent context');
+  console.log('2. Passthrough instructions are injected as a HumanMessage');
+  console.log('3. Multi-turn conversations work correctly after handoffs\n');
+
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  /** Track which agent is responding */
+  let currentAgent = '';
+
+  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 runStep = data as t.RunStep;
+        if (runStep.agentId) {
+          currentAgent = runStep.agentId;
+          console.log(`\n[Agent: ${currentAgent}] Processing...`);
+        }
+        aggregateContent({ event, data: runStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        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.log('====== ON_MESSAGE_DELTA ======');
+        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 { name?: string };
+        if (toolData?.name?.includes('transfer_to_')) {
+          const specialist = toolData.name.replace('lc_transfer_to_', '');
+          console.log(`\n🔀 Handing off to: ${specialist}`);
+        }
+      },
+    },
+  };
+
+  /**
+   * Create agents:
+   * - coordinator: Decides when to hand off to specialist
+   * - specialist: Handles specific tasks delegated by coordinator
+   */
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'coordinator',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1-mini',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are a Task Coordinator. Your role is to:
+1. Understand user requests
+2. If the request involves technical analysis, use the transfer_to_specialist tool to hand off
+3. When handing off, provide clear instructions about what needs to be done
+
+IMPORTANT: When using the handoff tool, include specific instructions for the specialist.`,
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'specialist',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        modelName: 'gpt-4.1-mini',
+        apiKey: process.env.OPENAI_API_KEY,
+      },
+      instructions: `You are a Technical Specialist. When you receive a request:
+1. Carefully read any instructions provided
+2. Provide a detailed technical response
+3. Do NOT just acknowledge - provide substantive help
+
+IMPORTANT: You are the specialist - provide a complete, helpful response to the task.`,
+      maxContextTokens: 8000,
+    },
+  ];
+
+  /** Create handoff edge with passthrough instructions */
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'coordinator',
+      to: 'specialist',
+      description: 'Transfer to technical specialist for analysis',
+      edgeType: 'handoff',
+      prompt: 'Specific instructions for the specialist about what to analyze',
+      promptKey: 'instructions',
+    },
+  ];
+
+  const runConfig: t.RunConfig = {
+    runId: `handoff-test-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  const run = await Run.create(runConfig);
+
+  const config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    streamMode: string;
+  } = {
+    configurable: {
+      thread_id: 'handoff-test-conversation-1',
+    },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  /** TURN 1: Initial request that triggers handoff */
+  console.log('\n' + '─'.repeat(60));
+  console.log('TURN 1: Initial request (should trigger handoff)');
+  console.log('─'.repeat(60));
+
+  const userMessage1 = `
+    Hi! Can you help me understand the time complexity of quicksort?
+    I need a technical explanation.
+  `;
+
+  conversationHistory.push(new HumanMessage(userMessage1));
+  console.log('\nUser:', userMessage1.trim());
+  console.log('\nResponse:');
+
+  let inputs = { messages: conversationHistory };
+  await run.processStream(inputs, config);
+  const messages1 = run.getRunMessages();
+  if (messages1) {
+    conversationHistory.push(...messages1);
+  }
+
+  console.log('\n');
+
+  /** TURN 2: Follow-up question to test multi-turn after handoff */
+  console.log('\n' + '─'.repeat(60));
+  console.log('TURN 2: Follow-up question (tests context after handoff)');
+  console.log('─'.repeat(60));
+
+  const userMessage2 = `
+    Thanks! Can you also explain the space complexity and when quicksort 
+    might not be the best choice?
+  `;
+
+  conversationHistory.push(new HumanMessage(userMessage2));
+  console.log('\nUser:', userMessage2.trim());
+  console.log('\nResponse:');
+
+  inputs = { messages: conversationHistory };
+  await run.processStream(inputs, config);
+  const messages2 = run.getRunMessages();
+  if (messages2) {
+    conversationHistory.push(...messages2);
+  }
+
+  console.log('\n');
+
+  /** TURN 3: Another follow-up to verify sustained conversation */
+  console.log('\n' + '─'.repeat(60));
+  console.log('TURN 3: Third turn (tests sustained multi-turn)');
+  console.log('─'.repeat(60));
+
+  const userMessage3 = `
+    Great explanation! One more question - how does quicksort compare 
+    to mergesort in practice?
+  `;
+
+  conversationHistory.push(new HumanMessage(userMessage3));
+  console.log('\nUser:', userMessage3.trim());
+  console.log('\nResponse:');
+
+  inputs = { messages: conversationHistory };
+  await run.processStream(inputs, config);
+  const messages3 = run.getRunMessages();
+  if (messages3) {
+    conversationHistory.push(...messages3);
+  }
+
+  /** Summary */
+  console.log('\n\n' + '='.repeat(60));
+  console.log('TEST SUMMARY');
+  console.log('='.repeat(60));
+  console.log('\nTotal messages in conversation:', conversationHistory.length);
+  console.log('\nMessage types:');
+
+  for (let i = 0; i < conversationHistory.length; i++) {
+    const msg = conversationHistory[i];
+    const type = msg.getType();
+    const preview =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 50).replace(/\n/g, ' ')
+        : '[complex content]';
+    console.log(`  ${i + 1}. [${type}] ${preview}...`);
+  }
+
+  console.log('\n✅ Test completed. Review the output above to verify:');
+  console.log('   - Specialist received and acted on instructions');
+  console.log('   - No premature end tokens after handoff');
+  console.log('   - Multi-turn conversation continued smoothly');
+}
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  console.log('\nConversation history at failure:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});
+
+process.on('uncaughtException', (err) => {
+  console.error('Uncaught Exception:', err);
+});
+
+testHandoffPreamble().catch((err) => {
+  console.error('Test failed:', err);
+  console.log('\nConversation history at failure:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});

package/src/stream.ts

@@ -583,6 +583,17 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         tool_call: newToolCall,
       };
     }
+
+    // Apply agentId (for MultiAgentGraph) and groupId (for parallel execution) to content parts
+    // - agentId present → MultiAgentGraph (show agent labels)
+    // - groupId present → parallel execution (render columns)
+    const meta = contentMetaMap.get(index);
+    if (meta?.agentId != null) {
+      (contentParts[index] as t.MessageContentComplex).agentId = meta.agentId;
+    }
+    if (meta?.groupId != null) {
+      (contentParts[index] as t.MessageContentComplex).groupId = meta.groupId;
+    }
   };
 
   const aggregateContent = ({
@@ -727,10 +738,5 @@ export function createContentAggregator(): t.ContentAggregatorResult {
     }
   };
 
-  return {
-    contentParts,
-    aggregateContent,
-    stepMap,
-    contentMetadataMap: contentMetaMap,
-  };
+  return { contentParts, aggregateContent, stepMap };
 }

package/src/types/stream.ts

@@ -343,6 +343,10 @@ export type MessageContentComplex = (
     })
 ) & {
   tool_call_ids?: string[];
+  // Optional agentId for parallel execution attribution
+  agentId?: string;
+  // Optional groupId for parallel group attribution
+  groupId?: number;
 };
 
 export interface TMessage {
@@ -406,20 +410,8 @@ export type ContentAggregator = ({
         result: ToolEndEvent;
       };
 }) => void;
-/**
- * Metadata for content parts in multi-agent runs.
- * - agentId: present for all MultiAgentGraph runs (enables agent labels in UI)
- * - groupId: present only for parallel execution (enables column rendering)
- */
-export type ContentMetadata = {
-  agentId?: string;
-  groupId?: number;
-};
-
 export type ContentAggregatorResult = {
   stepMap: Map<string, RunStep | undefined>;
   contentParts: Array<MessageContentComplex | undefined>;
-  /** Map of content index to metadata (agentId, groupId). Only populated for MultiAgentGraph runs. */
-  contentMetadataMap: Map<number, ContentMetadata>;
   aggregateContent: ContentAggregator;
 };