@librechat/agents 3.0.0-rc11 → 3.0.0-rc13

package/dist/types/agents/AgentContext.d.ts

@@ -56,7 +56,9 @@ export declare class AgentContext {
     systemRunnable?: Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>>;
     /** Promise for token calculation initialization */
     tokenCalculationPromise?: Promise<void>;
-    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, }: {
+    /** Format content blocks as strings (for legacy compatibility) */
+    useLegacyContent: boolean;
+    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         provider: Providers;
         clientOptions?: t.ClientOptions;
@@ -70,6 +72,7 @@ export declare class AgentContext {
         reasoningKey?: 'reasoning_content' | 'reasoning';
         toolEnd?: boolean;
         instructionTokens?: number;
+        useLegacyContent?: boolean;
     });
     /**
      * Create system runnable from instructions and calculate tokens if tokenCounter is available

package/dist/types/instrumentation.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/messages/cache.d.ts

@@ -0,0 +1,8 @@
+import type { AnthropicMessage } from '@/types/messages';
+import { BaseMessage } from '@langchain/core/messages';
+/**
+ * Anthropic API: Adds cache control to the appropriate user messages in the payload.
+ * @param messages - The array of message objects.
+ * @returns - The updated array of message objects with cache control added.
+ */
+export declare function addCacheControl<T extends AnthropicMessage | BaseMessage>(messages: T[]): T[];

package/dist/types/messages/content.d.ts

@@ -0,0 +1,7 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Formats an array of messages for LangChain, making sure all content fields are strings
+ * @param {Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>} payload - The array of messages to format.
+ * @returns {Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>} - The array of formatted LangChain messages, including ToolMessages for tool calls.
+ */
+export declare const formatContentStrings: (payload: Array<BaseMessage>) => Array<BaseMessage>;

package/dist/types/messages/format.d.ts

@@ -1,4 +1,4 @@
-import { AIMessage, ToolMessage, BaseMessage, HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { AIMessage, ToolMessage, HumanMessage, SystemMessage } from '@langchain/core/messages';
 import type { MessageContentImageUrl } from '@langchain/core/messages';
 import type { MessageContentComplex, TPayload } from '@/types';
 import { Providers } from '@/common';
@@ -95,12 +95,6 @@ export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
 };
-/**
- * Formats an array of messages for LangChain, making sure all content fields are strings
- * @param payload - The array of messages to format.
- * @returns - The array of formatted LangChain messages, including ToolMessages for tool calls.
- */
-export declare const formatContentStrings: (payload: Array<BaseMessage>) => Array<BaseMessage>;
 /**
  * Adds a value at key 0 for system messages and shifts all key indices by one in an indexTokenCountMap.
  * This is useful when adding a system message at the beginning of a conversation.

package/dist/types/messages/index.d.ts

@@ -2,3 +2,5 @@ export * from './core';
 export * from './ids';
 export * from './prune';
 export * from './format';
+export * from './cache';
+export * from './content';

package/dist/types/run.d.ts

@@ -1,4 +1,5 @@
-import type { BaseMessage, MessageContentComplex } from '@langchain/core/messages';
+import './instrumentation';
+import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
 import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';

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

@@ -246,4 +246,6 @@ export interface AgentInputs {
     clientOptions?: ClientOptions;
     additional_instructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
+    /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
+    useLegacyContent?: boolean;
 }

package/dist/types/types/messages.d.ts

@@ -0,0 +1,4 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { BaseMessage } from '@langchain/core/messages';
+export type AnthropicMessages = Array<AnthropicMessage | BaseMessage>;
+export type AnthropicMessage = Anthropic.MessageParam;

package/dist/types/utils/misc.d.ts

@@ -1,3 +1,4 @@
+export declare function isPresent(value: string | null | undefined): value is string;
 /**
  * Recursively unescapes all string values in an object
  * @param obj The object to unescape

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.0.00-rc11",
+  "version": "3.0.00-rc13",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -105,6 +105,10 @@
     "@langchain/ollama": "^0.2.3",
     "@langchain/openai": "0.5.18",
     "@langchain/xai": "^0.0.3",
+    "@langfuse/langchain": "^4.3.0",
+    "@langfuse/otel": "^4.3.0",
+    "@langfuse/tracing": "^4.3.0",
+    "@opentelemetry/sdk-node": "^0.207.0",
     "cheerio": "^1.0.0",
     "dotenv": "^16.4.7",
     "https-proxy-agent": "^7.0.6",

package/src/agents/AgentContext.ts

@@ -37,6 +37,7 @@ export class AgentContext {
       streamBuffer,
       maxContextTokens,
       reasoningKey,
+      useLegacyContent,
     } = agentConfig;
 
     const agentContext = new AgentContext({
@@ -53,6 +54,7 @@ export class AgentContext {
       toolEnd,
       instructionTokens: 0,
       tokenCounter,
+      useLegacyContent,
     });
 
     if (tokenCounter) {
@@ -123,6 +125,8 @@ export class AgentContext {
   >;
   /** Promise for token calculation initialization */
   tokenCalculationPromise?: Promise<void>;
+  /** Format content blocks as strings (for legacy compatibility) */
+  useLegacyContent: boolean = false;
 
   constructor({
     agentId,
@@ -138,6 +142,7 @@ export class AgentContext {
     reasoningKey,
     toolEnd,
     instructionTokens,
+    useLegacyContent,
   }: {
     agentId: string;
     provider: Providers;
@@ -152,6 +157,7 @@ export class AgentContext {
     reasoningKey?: 'reasoning_content' | 'reasoning';
     toolEnd?: boolean;
     instructionTokens?: number;
+    useLegacyContent?: boolean;
   }) {
     this.agentId = agentId;
     this.provider = provider;
@@ -173,6 +179,8 @@ export class AgentContext {
       this.instructionTokens = instructionTokens;
     }
 
+    this.useLegacyContent = useLegacyContent ?? false;
+
     this.systemRunnable = this.createSystemRunnable();
   }
 

package/src/graphs/Graph.ts

@@ -41,7 +41,9 @@ import {
   convertMessagesToContent,
   modifyDeltaProperties,
   formatArtifactPayload,
+  formatContentStrings,
   createPruneMessages,
+  addCacheControl,
 } from '@/messages';
 import {
   resetIfNotEmpty,
@@ -608,7 +610,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         messagesToUse = context;
       }
 
-      const finalMessages = messagesToUse;
+      let finalMessages = messagesToUse;
+      if (agentContext.useLegacyContent) {
+        finalMessages = formatContentStrings(finalMessages);
+      }
+
       const lastMessageX =
         finalMessages.length >= 2
           ? finalMessages[finalMessages.length - 2]
@@ -642,6 +648,22 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         formatArtifactPayload(finalMessages);
       }
 
+      if (agentContext.provider === Providers.ANTHROPIC) {
+        const anthropicOptions = agentContext.clientOptions as
+          | t.AnthropicClientOptions
+          | undefined;
+        const defaultHeaders = anthropicOptions?.clientOptions
+          ?.defaultHeaders as Record<string, string> | undefined;
+        const anthropicBeta = defaultHeaders?.['anthropic-beta'];
+
+        if (
+          typeof anthropicBeta === 'string' &&
+          anthropicBeta.includes('prompt-caching')
+        ) {
+          finalMessages = addCacheControl<BaseMessage>(finalMessages);
+        }
+      }
+
       if (
         agentContext.lastStreamCall != null &&
         agentContext.streamBuffer != null

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/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/openai/index.ts

@@ -248,11 +248,6 @@ export class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
   getReasoningParams(
     options?: this['ParsedCallOptions']
   ): OpenAIClient.Reasoning | undefined {
-    const lc_name = (this.constructor as typeof ChatOpenAI).lc_name();
-    if (lc_name === 'LibreChatOpenAI' && !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) {

package/src/messages/cache.test.ts

@@ -0,0 +1,262 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { AnthropicMessages } from '@/types/messages';
+import { addCacheControl } from './cache';
+
+describe('addCacheControl', () => {
+  test('should add cache control to the last two user messages with array content', () => {
+    const messages: AnthropicMessages = [
+      { role: 'user', content: [{ type: 'text', text: 'Hello' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'Hi there' }] },
+      { role: 'user', content: [{ type: 'text', text: 'How are you?' }] },
+      {
+        role: 'assistant',
+        content: [{ type: 'text', text: 'I\'m doing well, thanks!' }],
+      },
+      { role: 'user', content: [{ type: 'text', text: 'Great!' }] },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content[0]).not.toHaveProperty('cache_control');
+    expect(
+      (result[2].content[0] as Anthropic.TextBlockParam).cache_control
+    ).toEqual({ type: 'ephemeral' });
+    expect(
+      (result[4].content[0] as Anthropic.TextBlockParam).cache_control
+    ).toEqual({ type: 'ephemeral' });
+  });
+
+  test('should add cache control to the last two user messages with string content', () => {
+    const messages: AnthropicMessages = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: 'How are you?' },
+      { role: 'assistant', content: 'I\'m doing well, thanks!' },
+      { role: 'user', content: 'Great!' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content).toBe('Hello');
+    expect(result[2].content[0]).toEqual({
+      type: 'text',
+      text: 'How are you?',
+      cache_control: { type: 'ephemeral' },
+    });
+    expect(result[4].content[0]).toEqual({
+      type: 'text',
+      text: 'Great!',
+      cache_control: { type: 'ephemeral' },
+    });
+  });
+
+  test('should handle mixed string and array content', () => {
+    const messages: AnthropicMessages = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: [{ type: 'text', text: 'How are you?' }] },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content[0]).toEqual({
+      type: 'text',
+      text: 'Hello',
+      cache_control: { type: 'ephemeral' },
+    });
+    expect(
+      (result[2].content[0] as Anthropic.TextBlockParam).cache_control
+    ).toEqual({ type: 'ephemeral' });
+  });
+
+  test('should handle less than two user messages', () => {
+    const messages: AnthropicMessages = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content[0]).toEqual({
+      type: 'text',
+      text: 'Hello',
+      cache_control: { type: 'ephemeral' },
+    });
+    expect(result[1].content).toBe('Hi there');
+  });
+
+  test('should return original array if no user messages', () => {
+    const messages: AnthropicMessages = [
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'assistant', content: 'How can I help?' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result).toEqual(messages);
+  });
+
+  test('should handle empty array', () => {
+    const messages: AnthropicMessages = [];
+    const result = addCacheControl(messages);
+    expect(result).toEqual([]);
+  });
+
+  test('should handle non-array input', () => {
+    const messages = 'not an array';
+    /** @ts-expect-error - This is a test */
+    const result = addCacheControl(messages);
+    expect(result).toBe('not an array');
+  });
+
+  test('should not modify assistant messages', () => {
+    const messages: AnthropicMessages = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: 'How are you?' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[1].content).toBe('Hi there');
+  });
+
+  test('should handle multiple content items in user messages', () => {
+    const messages: AnthropicMessages = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Hello' },
+          {
+            type: 'image',
+            source: { type: 'url', url: 'http://example.com/image.jpg' },
+          },
+          { type: 'text', text: 'This is an image' },
+        ],
+      },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: 'How are you?' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content[0]).not.toHaveProperty('cache_control');
+    expect(result[0].content[1]).not.toHaveProperty('cache_control');
+    expect(
+      (result[0].content[2] as Anthropic.TextBlockParam).cache_control
+    ).toEqual({ type: 'ephemeral' });
+    expect(result[2].content[0]).toEqual({
+      type: 'text',
+      text: 'How are you?',
+      cache_control: { type: 'ephemeral' },
+    });
+  });
+
+  test('should handle an array with mixed content types', () => {
+    const messages: AnthropicMessages = [
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+      { role: 'user', content: [{ type: 'text', text: 'How are you?' }] },
+      { role: 'assistant', content: 'I\'m doing well, thanks!' },
+      { role: 'user', content: 'Great!' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content).toEqual('Hello');
+    expect(result[2].content[0]).toEqual({
+      type: 'text',
+      text: 'How are you?',
+      cache_control: { type: 'ephemeral' },
+    });
+    expect(result[4].content).toEqual([
+      {
+        type: 'text',
+        text: 'Great!',
+        cache_control: { type: 'ephemeral' },
+      },
+    ]);
+    expect(result[1].content).toBe('Hi there');
+    expect(result[3].content).toBe('I\'m doing well, thanks!');
+  });
+
+  test('should handle edge case with multiple content types', () => {
+    const messages: AnthropicMessages = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: 'image/png',
+              data: 'some_base64_string',
+            },
+          },
+          {
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: 'image/png',
+              data: 'another_base64_string',
+            },
+          },
+          { type: 'text', text: 'what do all these images have in common' },
+        ],
+      },
+      { role: 'assistant', content: 'I see multiple images.' },
+      { role: 'user', content: 'Correct!' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content[0]).not.toHaveProperty('cache_control');
+    expect(result[0].content[1]).not.toHaveProperty('cache_control');
+    expect(
+      (result[0].content[2] as Anthropic.ImageBlockParam).cache_control
+    ).toEqual({ type: 'ephemeral' });
+    expect(result[2].content[0]).toEqual({
+      type: 'text',
+      text: 'Correct!',
+      cache_control: { type: 'ephemeral' },
+    });
+  });
+
+  test('should handle user message with no text block', () => {
+    const messages: AnthropicMessages = [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: 'image/png',
+              data: 'some_base64_string',
+            },
+          },
+          {
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: 'image/png',
+              data: 'another_base64_string',
+            },
+          },
+        ],
+      },
+      { role: 'assistant', content: 'I see two images.' },
+      { role: 'user', content: 'Correct!' },
+    ];
+
+    const result = addCacheControl(messages);
+
+    expect(result[0].content[0]).not.toHaveProperty('cache_control');
+    expect(result[0].content[1]).not.toHaveProperty('cache_control');
+    expect(result[2].content[0]).toEqual({
+      type: 'text',
+      text: 'Correct!',
+      cache_control: { type: 'ephemeral' },
+    });
+  });
+});

package/src/messages/cache.ts

@@ -0,0 +1,56 @@
+import type { AnthropicMessage } from '@/types/messages';
+import type Anthropic from '@anthropic-ai/sdk';
+import { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * Anthropic API: Adds cache control to the appropriate user messages in the payload.
+ * @param messages - The array of message objects.
+ * @returns - The updated array of message objects with cache control added.
+ */
+export function addCacheControl<T extends AnthropicMessage | BaseMessage>(
+  messages: T[]
+): T[] {
+  if (!Array.isArray(messages) || messages.length < 2) {
+    return messages;
+  }
+
+  const updatedMessages = [...messages];
+  let userMessagesModified = 0;
+
+  for (
+    let i = updatedMessages.length - 1;
+    i >= 0 && userMessagesModified < 2;
+    i--
+  ) {
+    const message = updatedMessages[i];
+    if ('getType' in message && message.getType() !== 'human') {
+      continue;
+    } else if ('role' in message && message.role !== 'user') {
+      continue;
+    }
+
+    if (typeof message.content === 'string') {
+      message.content = [
+        {
+          type: 'text',
+          text: message.content,
+          cache_control: { type: 'ephemeral' },
+        },
+      ];
+      userMessagesModified++;
+    } else if (Array.isArray(message.content)) {
+      for (let j = message.content.length - 1; j >= 0; j--) {
+        const contentPart = message.content[j];
+        if ('type' in contentPart && contentPart.type === 'text') {
+          (contentPart as Anthropic.TextBlockParam).cache_control = {
+            type: 'ephemeral',
+          };
+          userMessagesModified++;
+          break;
+        }
+      }
+    }
+  }
+
+  return updatedMessages;
+}