@librechat/agents 3.0.0-rc8 → 3.0.0

package/src/graphs/MultiAgentGraph.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { tool } from '@langchain/core/tools';
+import { PromptTemplate } from '@langchain/core/prompts';
 import {
   ToolMessage,
   HumanMessage,
   getBufferString,
 } from '@langchain/core/messages';
-import { ChatPromptTemplate } from '@langchain/core/prompts';
 import {
   END,
   START,
@@ -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[];
@@ -328,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),
       });
     }
 
@@ -416,16 +508,16 @@ export class MultiAgentGraph extends StandardGraph {
           let effectiveExcludeResults = excludeResults;
 
           if (typeof prompt === 'function') {
-            promptText = prompt(state.messages, this.startIndex);
+            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 = ChatPromptTemplate.fromTemplate(prompt);
-              const formattedPromptValue = await promptTemplate.invoke({
+              const promptTemplate = PromptTemplate.fromTemplate(prompt);
+              const result = await promptTemplate.invoke({
                 results: resultsString,
               });
-              promptText = formattedPromptValue.messages[0].content.toString();
+              promptText = result.value;
               effectiveExcludeResults =
                 excludeResults !== false && promptText !== '';
             } else {
@@ -474,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/instrumentation.ts

@@ -0,0 +1,22 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { isPresent } from '@/utils/misc';
+
+if (
+  isPresent(process.env.LANGFUSE_SECRET_KEY) &&
+  isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
+  isPresent(process.env.LANGFUSE_BASE_URL)
+) {
+  const langfuseSpanProcessor = new LangfuseSpanProcessor({
+    publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+    secretKey: process.env.LANGFUSE_SECRET_KEY,
+    baseUrl: process.env.LANGFUSE_BASE_URL,
+    environment: process.env.NODE_ENV ?? 'development',
+  });
+
+  const sdk = new NodeSDK({
+    spanProcessors: [langfuseSpanProcessor],
+  });
+
+  sdk.start();
+}

package/src/llm/anthropic/index.ts

@@ -135,12 +135,18 @@ export class CustomAnthropic extends ChatAnthropicMessages {
   private message_delta: AnthropicMessageDeltaEvent | undefined;
   private tools_in_params?: boolean;
   private emitted_usage?: boolean;
+  top_k: number | undefined;
   constructor(fields?: CustomAnthropicInput) {
     super(fields);
     this.resetTokenEvents();
+    this.setDirectFields(fields);
     this._lc_stream_delay = fields?._lc_stream_delay ?? 25;
   }
 
+  static lc_name(): 'LibreChatAnthropic' {
+    return 'LibreChatAnthropic';
+  }
+
   /**
    * Get the parameters used to invoke the model
    */
@@ -158,7 +164,7 @@ export class CustomAnthropic extends ChatAnthropicMessages {
       | undefined = handleToolChoice(options?.tool_choice);
 
     if (this.thinking.type === 'enabled') {
-      if (this.topK !== -1 && (this.topK as number | undefined) != null) {
+      if (this.top_k !== -1 && (this.top_k as number | undefined) != null) {
         throw new Error('topK is not supported when thinking is enabled');
       }
       if (this.topP !== -1 && (this.topP as number | undefined) != null) {
@@ -187,7 +193,7 @@ export class CustomAnthropic extends ChatAnthropicMessages {
     return {
       model: this.model,
       temperature: this.temperature,
-      top_k: this.topK,
+      top_k: this.top_k,
       top_p: this.topP,
       stop_sequences: options?.stop ?? this.stopSequences,
       stream: this.streaming,
@@ -244,6 +250,21 @@ export class CustomAnthropic extends ChatAnthropicMessages {
     this.tools_in_params = undefined;
   }
 
+  setDirectFields(fields?: CustomAnthropicInput): void {
+    this.temperature = fields?.temperature ?? undefined;
+    this.topP = fields?.topP ?? undefined;
+    this.top_k = fields?.topK;
+    if (this.temperature === -1 || this.temperature === 1) {
+      this.temperature = undefined;
+    }
+    if (this.topP === -1) {
+      this.topP = undefined;
+    }
+    if (this.top_k === -1) {
+      this.top_k = undefined;
+    }
+  }
+
   private createGenerationChunk({
     token,
     chunk,

package/src/llm/anthropic/llm.spec.ts

@@ -58,7 +58,7 @@ async function invoke(
 const extendedThinkingModelName = 'claude-3-7-sonnet-20250219';
 
 // use this for tests involving citations
-const citationsModelName = 'claude-3-5-sonnet-20241022';
+const citationsModelName = 'claude-sonnet-4-5-20250929';
 
 // use this for tests involving PDF documents
 const pdfModelName = 'claude-3-5-haiku-20241022';

package/src/llm/google/index.ts

@@ -107,6 +107,10 @@ export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
     this.streamUsage = fields.streamUsage ?? this.streamUsage;
   }
 
+  static lc_name(): 'LibreChatGoogleGenerativeAI' {
+    return 'LibreChatGoogleGenerativeAI';
+  }
+
   invocationParams(
     options?: this['ParsedCallOptions']
   ): Omit<GenerateContentRequest, 'contents'> {

package/src/llm/google/utils/common.ts

@@ -301,6 +301,20 @@ function _convertLangChainContentToPart(
         mimeType,
       },
     };
+  } else if (
+    content.type === 'document' ||
+    content.type === 'audio' ||
+    content.type === 'video'
+  ) {
+    if (!isMultimodalModel) {
+      throw new Error(`This model does not support ${content.type}s`);
+    }
+    return {
+      inlineData: {
+        data: content.data,
+        mimeType: content.mimeType,
+      },
+    };
   } else if (content.type === 'media') {
     return messageContentMedia(content);
   } else if (content.type === 'tool_use') {

package/src/llm/ollama/index.ts

@@ -13,6 +13,9 @@ import {
 } from './utils';
 
 export class ChatOllama extends BaseChatOllama {
+  static lc_name(): 'LibreChatOllama' {
+    return 'LibreChatOllama';
+  }
   async *_streamResponseChunks(
     messages: BaseMessage[],
     options: this['ParsedCallOptions'],

package/src/llm/openai/index.ts

@@ -210,6 +210,9 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
+  static lc_name(): string {
+    return 'LibreChatOpenAI';
+  }
   protected _getClientOptions(
     options?: OpenAICoreRequestOptions
   ): OpenAICoreRequestOptions {
@@ -245,10 +248,6 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
   getReasoningParams(
     options?: this['ParsedCallOptions']
   ): OpenAIClient.Reasoning | undefined {
-    if (!isReasoningModel(this.model)) {
-      return;
-    }
-
     // apply options in reverse order of importance -- newer options supersede older options
     let reasoning: OpenAIClient.Reasoning | undefined;
     if (this.reasoning !== undefined) {
@@ -360,6 +359,10 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
       } else if ('reasoning' in delta) {
         chunk.additional_kwargs.reasoning_content = delta.reasoning;
       }
+      if ('provider_specific_fields' in delta) {
+        chunk.additional_kwargs.provider_specific_fields =
+          delta.provider_specific_fields;
+      }
       defaultRole = delta.role ?? defaultRole;
       const newTokenIndices = {
         prompt: options.promptIndex ?? 0,
@@ -463,6 +466,9 @@ export class AzureChatOpenAI extends OriginalAzureChatOpenAI {
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
+  static lc_name(): 'LibreChatAzureOpenAI' {
+    return 'LibreChatAzureOpenAI';
+  }
   /**
    * Returns backwards compatible reasoning parameters from constructor params and call options
    * @internal
@@ -607,6 +613,9 @@ export class ChatDeepSeek extends OriginalChatDeepSeek {
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }
+  static lc_name(): 'LibreChatDeepSeek' {
+    return 'LibreChatDeepSeek';
+  }
   protected _getClientOptions(
     options?: OpenAICoreRequestOptions
   ): OpenAICoreRequestOptions {
@@ -679,6 +688,10 @@ export class ChatXAI extends OriginalChatXAI {
     }
   }
 
+  static lc_name(): 'LibreChatXAI' {
+    return 'LibreChatXAI';
+  }
+
   public get exposedClient(): CustomOpenAIClient {
     return this.client;
   }

package/src/llm/openai/utils/index.ts

@@ -298,10 +298,16 @@ export function _convertMessagesToOpenAIParams(
       role = 'developer';
     }
 
+    let hasAnthropicThinkingBlock: boolean = false;
+
     const content =
       typeof message.content === 'string'
         ? message.content
         : message.content.map((m) => {
+          if ('type' in m && m.type === 'thinking') {
+            hasAnthropicThinkingBlock = true;
+            return m;
+          }
           if (isDataContentBlock(m)) {
             return convertToProviderContentBlock(
               m,
@@ -326,7 +332,7 @@ export function _convertMessagesToOpenAIParams(
       completionParam.tool_calls = message.tool_calls.map(
         convertLangChainToolCallToOpenAI
       );
-      completionParam.content = '';
+      completionParam.content = hasAnthropicThinkingBlock ? content : '';
     } else {
       if (message.additional_kwargs.tool_calls != null) {
         completionParam.tool_calls = message.additional_kwargs.tool_calls;

package/src/llm/openrouter/index.ts

@@ -1,27 +1,36 @@
-import type { ChatOpenAICallOptions, OpenAIClient } from '@langchain/openai';
+import { ChatOpenAI } from '@/llm/openai';
 import type {
-  AIMessageChunk,
-  HumanMessageChunk,
-  SystemMessageChunk,
   FunctionMessageChunk,
+  SystemMessageChunk,
+  HumanMessageChunk,
   ToolMessageChunk,
   ChatMessageChunk,
+  AIMessageChunk,
 } from '@langchain/core/messages';
-import { ChatOpenAI } from '@/llm/openai';
+import type {
+  ChatOpenAICallOptions,
+  OpenAIChatInput,
+  OpenAIClient,
+} from '@langchain/openai';
 
 export interface ChatOpenRouterCallOptions extends ChatOpenAICallOptions {
   include_reasoning?: boolean;
+  modelKwargs?: OpenAIChatInput['modelKwargs'];
 }
 export class ChatOpenRouter extends ChatOpenAI {
   constructor(_fields: Partial<ChatOpenRouterCallOptions>) {
-    const { include_reasoning, ...fields } = _fields;
+    const { include_reasoning, modelKwargs = {}, ...fields } = _fields;
     super({
       ...fields,
       modelKwargs: {
+        ...modelKwargs,
         include_reasoning,
       },
     });
   }
+  static lc_name(): 'LibreChatOpenRouter' {
+    return 'LibreChatOpenRouter';
+  }
   protected override _convertOpenAIDeltaToBaseMessageChunk(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     delta: Record<string, any>,

package/src/llm/vertexai/index.ts

@@ -313,8 +313,8 @@ export class ChatVertexAI extends ChatGoogle {
   lc_namespace = ['langchain', 'chat_models', 'vertexai'];
   dynamicThinkingBudget = false;
 
-  static lc_name(): 'ChatVertexAI' {
-    return 'ChatVertexAI';
+  static lc_name(): 'LibreChatVertexAI' {
+    return 'LibreChatVertexAI';
   }
 
   constructor(fields?: VertexAIClientOptions) {