@librechat/agents 3.1.91 → 3.1.92

package/src/langfuse.ts

@@ -1,8 +1,8 @@
 import { CallbackHandler } from '@langfuse/langchain';
-import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { isDefaultExportSpan, LangfuseSpanProcessor } from '@langfuse/otel';
 import {
+  LangfuseOtelSpanAttributes,
   createObservationAttributes,
-  createTraceAttributes,
 } from '@langfuse/tracing';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
@@ -10,16 +10,20 @@ import { SpanStatusCode } from '@opentelemetry/api';
 import type { Serialized } from '@langchain/core/load/serializable';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { LLMResult } from '@langchain/core/outputs';
-import type { Span } from '@opentelemetry/api';
+import type { Attributes, Span } from '@opentelemetry/api';
 import type * as t from '@/types';
 import { isPresent } from '@/utils/misc';
 
-type TraceMetadata = Record<string, unknown>;
+const TRACE_METADATA_MAX_LENGTH = 200;
+const LANGFUSE_TRACER_NAME = 'langfuse-sdk';
+
+export type LangfuseTraceMetadata = Record<string, string>;
 
 type LangfuseHandlerParams = {
   userId?: string;
   sessionId?: string;
-  traceMetadata?: TraceMetadata;
+  traceMetadata?: LangfuseTraceMetadata;
+  tags?: string[];
 };
 
 type AgentLangfuseHandlerParams = LangfuseHandlerParams & {
@@ -32,6 +36,49 @@ type ResolvedLangfuseConfig = t.LangfuseConfig & {
   secretKey: string;
 };
 
+function getEnvLangfuseBaseUrl(): string | undefined {
+  return process.env.LANGFUSE_BASE_URL ?? process.env.LANGFUSE_BASEURL;
+}
+
+function createTraceMetadata(
+  metadata: Record<string, unknown>
+): LangfuseTraceMetadata {
+  const traceMetadata: LangfuseTraceMetadata = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value == null) {
+      continue;
+    }
+    const stringValue = typeof value === 'string' ? value : String(value);
+    if (
+      stringValue.trim() === '' ||
+      stringValue.length > TRACE_METADATA_MAX_LENGTH
+    ) {
+      continue;
+    }
+    traceMetadata[key] = stringValue;
+  }
+  return traceMetadata;
+}
+
+export function createLangfuseTraceMetadata({
+  messageId,
+  parentMessageId,
+  agentId,
+  agentName,
+}: {
+  messageId?: unknown;
+  parentMessageId?: unknown;
+  agentId?: unknown;
+  agentName?: unknown;
+}): LangfuseTraceMetadata {
+  return createTraceMetadata({
+    messageId,
+    parentMessageId,
+    agentId,
+    agentName,
+  });
+}
+
 function getModelName(serialized: Serialized): string {
   const serializedRecord = serialized as unknown as Record<string, unknown>;
   const kwargs = serializedRecord.kwargs as Record<string, unknown> | undefined;
@@ -99,11 +146,39 @@ function getUsageDetails(
     : undefined;
 }
 
-function getTraceName(traceMetadata?: TraceMetadata): string {
+export function getLangfuseTraceName(
+  traceMetadata?: LangfuseTraceMetadata,
+  fallback: string = 'LibreChat Agent'
+): string {
   const agentName = traceMetadata?.agentName;
-  return typeof agentName === 'string' && agentName.trim() !== ''
-    ? `LibreChat Agent: ${agentName}`
-    : 'LibreChat Agent';
+  return isPresent(agentName) ? `${fallback}: ${agentName}` : fallback;
+}
+
+function getTraceAttributes({
+  userId,
+  sessionId,
+  traceMetadata,
+  tags,
+}: LangfuseHandlerParams): Attributes {
+  const attributes: Attributes = {
+    [LangfuseOtelSpanAttributes.TRACE_NAME]:
+      getLangfuseTraceName(traceMetadata),
+  };
+
+  if (isPresent(userId)) {
+    attributes[LangfuseOtelSpanAttributes.TRACE_USER_ID] = userId;
+  }
+  if (isPresent(sessionId)) {
+    attributes[LangfuseOtelSpanAttributes.TRACE_SESSION_ID] = sessionId;
+  }
+  if (tags != null && tags.length > 0) {
+    attributes[LangfuseOtelSpanAttributes.TRACE_TAGS] = tags;
+  }
+  for (const [key, value] of Object.entries(traceMetadata ?? {})) {
+    attributes[`${LangfuseOtelSpanAttributes.TRACE_METADATA}.${key}`] = value;
+  }
+
+  return attributes;
 }
 
 export class LangfuseAgentCallbackHandler extends BaseCallbackHandler {
@@ -113,7 +188,8 @@ export class LangfuseAgentCallbackHandler extends BaseCallbackHandler {
   private readonly processor: LangfuseSpanProcessor;
   private readonly userId?: string;
   private readonly sessionId?: string;
-  private readonly traceMetadata?: TraceMetadata;
+  private readonly traceMetadata?: LangfuseTraceMetadata;
+  private readonly tags?: string[];
   private readonly spans = new Map<string, Span>();
 
   constructor({
@@ -121,11 +197,13 @@ export class LangfuseAgentCallbackHandler extends BaseCallbackHandler {
     userId,
     sessionId,
     traceMetadata,
+    tags,
   }: LangfuseHandlerParams & { langfuse: ResolvedLangfuseConfig }) {
     super();
     this.userId = userId;
     this.sessionId = sessionId;
     this.traceMetadata = traceMetadata;
+    this.tags = tags;
     this.processor = new LangfuseSpanProcessor({
       publicKey: langfuse.publicKey,
       secretKey: langfuse.secretKey,
@@ -135,6 +213,9 @@ export class LangfuseAgentCallbackHandler extends BaseCallbackHandler {
         process.env.NODE_ENV ??
         'development',
       exportMode: 'immediate',
+      shouldExportSpan: ({ otelSpan }): boolean =>
+        isDefaultExportSpan(otelSpan) ||
+        otelSpan.instrumentationScope.name === LANGFUSE_TRACER_NAME,
     });
     this.provider = new BasicTracerProvider({
       spanProcessors: [this.processor],
@@ -160,16 +241,16 @@ export class LangfuseAgentCallbackHandler extends BaseCallbackHandler {
       return;
     }
 
-    const tracer = this.provider.getTracer('librechat-agents-langfuse');
+    const tracer = this.provider.getTracer(LANGFUSE_TRACER_NAME);
     const spanName =
       typeof name === 'string' && name.trim() !== '' ? name : getModelName(llm);
     const span = tracer.startSpan(spanName, {
       attributes: {
-        ...createTraceAttributes({
-          name: getTraceName(this.traceMetadata),
+        ...getTraceAttributes({
           userId: this.userId,
           sessionId: this.sessionId,
-          metadata: this.traceMetadata,
+          traceMetadata: this.traceMetadata,
+          tags: this.tags,
         }),
         ...createObservationAttributes('generation', {
           input,
@@ -312,6 +393,7 @@ export function createLangfuseHandler({
   userId,
   sessionId,
   traceMetadata,
+  tags,
 }: AgentLangfuseHandlerParams): LangfuseAgentCallbackHandler | undefined {
   if (!hasRequiredLangfuseConfig(langfuse)) {
     return undefined;
@@ -322,6 +404,7 @@ export function createLangfuseHandler({
     userId,
     sessionId,
     traceMetadata,
+    tags,
   });
 }
 
@@ -340,7 +423,7 @@ export function hasLangfuseEnvConfig(): boolean {
   return (
     isPresent(process.env.LANGFUSE_SECRET_KEY) &&
     isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&
-    isPresent(process.env.LANGFUSE_BASE_URL)
+    isPresent(getEnvLangfuseBaseUrl())
   );
 }
 

package/src/run.ts

@@ -30,10 +30,17 @@ import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { executeHooks } from '@/hooks';
 import { isOpenAILike } from '@/utils/llm';
+import {
+  appendCallbacks,
+  findCallback,
+  type CallbackEntry,
+} from '@/utils/callbacks';
 import {
   createLegacyLangfuseHandler,
+  createLangfuseTraceMetadata,
   createLangfuseHandler,
   disposeLangfuseHandler,
+  getLangfuseTraceName,
   hasExplicitLangfuseConfig,
   hasLangfuseEnvConfig,
   isLangfuseCallbackHandler,
@@ -598,42 +605,48 @@ export class Run<_T extends t.BaseGraphState> {
     /** Custom event callback to intercept and handle custom events */
     const customEventCallback = this.createCustomEventCallback();
 
-    const baseCallbacks = (config.callbacks as t.ProvidedCallbacks) ?? [];
     const streamCallbacks = streamOptions?.callbacks
       ? this.getCallbacks(streamOptions.callbacks)
-      : [];
+      : undefined;
 
     const customHandler = BaseCallbackHandler.fromMethods({
       [Callback.CUSTOM_EVENT]: customEventCallback,
     });
     customHandler.awaitHandlers = true;
 
-    config.callbacks = baseCallbacks
-      .concat(streamCallbacks)
-      .concat(customHandler);
+    config.callbacks = appendCallbacks(
+      config.callbacks,
+      streamCallbacks ? [streamCallbacks, customHandler] : [customHandler]
+    );
 
     if (
       hasLangfuseEnvConfig() &&
       !hasExplicitLangfuseConfig(this.Graph.agentContexts.values())
     ) {
-      const userId = config.configurable?.user_id;
-      const sessionId = config.configurable?.thread_id;
+      const userId =
+        typeof config.configurable?.user_id === 'string'
+          ? config.configurable.user_id
+          : undefined;
+      const sessionId =
+        typeof config.configurable?.thread_id === 'string'
+          ? config.configurable.thread_id
+          : undefined;
       const primaryContext = this.Graph.agentContexts.get(
         this.Graph.defaultAgentId
       );
-      const traceMetadata = {
+      const traceMetadata = createLangfuseTraceMetadata({
         messageId: this.id,
         parentMessageId: config.configurable?.requestBody?.parentMessageId,
         agentName: primaryContext?.name,
-      };
+      });
       const handler = createLegacyLangfuseHandler({
         userId,
         sessionId,
         traceMetadata,
+        tags: ['librechat', 'agent'],
       });
-      config.callbacks = (
-        (config.callbacks as t.ProvidedCallbacks) ?? []
-      ).concat([handler]);
+      config.runName = config.runName ?? getLangfuseTraceName(traceMetadata);
+      config.callbacks = appendCallbacks(config.callbacks, [handler]);
     }
 
     if (!this.id) {
@@ -1139,17 +1152,26 @@ export class Run<_T extends t.BaseGraphState> {
     titleMethod = TitleMethod.COMPLETION,
     titlePromptTemplate,
   }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {
-    let titleLangfuseHandler: unknown;
+    let titleLangfuseHandler: CallbackEntry | undefined;
+    const titleContext =
+      this.Graph == null
+        ? undefined
+        : this.Graph.agentContexts.get(this.Graph.defaultAgentId);
+    const traceMetadata = createLangfuseTraceMetadata({
+      messageId: 'title-' + this.id,
+      agentName: titleContext?.name,
+    });
+    const titleRunName = getLangfuseTraceName(traceMetadata, 'LibreChat Title');
+
     if (chainOptions != null) {
-      const userId = chainOptions.configurable?.user_id;
-      const sessionId = chainOptions.configurable?.thread_id;
-      const titleContext = this.Graph?.agentContexts.get(
-        this.Graph.defaultAgentId
-      );
-      const traceMetadata = {
-        messageId: 'title-' + this.id,
-        agentName: titleContext?.name,
-      };
+      const userId =
+        typeof chainOptions.configurable?.user_id === 'string'
+          ? chainOptions.configurable.user_id
+          : undefined;
+      const sessionId =
+        typeof chainOptions.configurable?.thread_id === 'string'
+          ? chainOptions.configurable.thread_id
+          : undefined;
       const hasExplicitLangfuse =
         this.Graph != null &&
         hasExplicitLangfuseConfig(this.Graph.agentContexts.values());
@@ -1159,20 +1181,20 @@ export class Run<_T extends t.BaseGraphState> {
           userId,
           sessionId,
           traceMetadata,
+          tags: ['librechat', 'title'],
         });
       } else if (hasLangfuseEnvConfig() && !hasExplicitLangfuse) {
         titleLangfuseHandler = createLegacyLangfuseHandler({
           userId,
           sessionId,
           traceMetadata,
+          tags: ['librechat', 'title'],
         });
       }
 
       if (titleLangfuseHandler != null) {
-        chainOptions.callbacks = (
-          (chainOptions.callbacks as t.ProvidedCallbacks) ?? []
-        ).concat([
-          titleLangfuseHandler as NonNullable<t.ProvidedCallbacks>[number],
+        chainOptions.callbacks = appendCallbacks(chainOptions.callbacks, [
+          titleLangfuseHandler,
         ]);
       }
     }
@@ -1236,6 +1258,7 @@ export class Run<_T extends t.BaseGraphState> {
     const invokeConfig = Object.assign({}, chainOptions, {
       run_id: this.id,
       runId: this.id,
+      runName: chainOptions?.runName ?? titleRunName,
     });
 
     try {
@@ -1247,9 +1270,10 @@ export class Run<_T extends t.BaseGraphState> {
       } catch (_e) {
         // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments
         // but preserve Langfuse tracing if it exists.
-        const langfuseHandler = (
-          invokeConfig.callbacks as t.ProvidedCallbacks
-        )?.find(isLangfuseCallbackHandler);
+        const langfuseHandler = findCallback(
+          invokeConfig.callbacks,
+          isLangfuseCallbackHandler
+        );
         const { callbacks: _cb, ...rest } = invokeConfig;
         const safeConfig = Object.assign({}, rest, {
           callbacks: langfuseHandler ? [langfuseHandler] : [],

package/src/specs/langfuse-callbacks.test.ts

@@ -0,0 +1,75 @@
+import { CallbackManager } from '@langchain/core/callbacks/manager';
+import { HumanMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+import { Run } from '@/run';
+import type * as t from '@/types';
+
+const mockSpan = {
+  end: jest.fn(),
+  setAttributes: jest.fn(),
+  setStatus: jest.fn(),
+};
+const mockStartSpan = jest.fn(() => mockSpan);
+const mockForceFlush = jest.fn();
+const mockShutdown = jest.fn();
+
+jest.mock('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+  isDefaultExportSpan: jest.fn(() => false),
+}));
+
+jest.mock('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: jest.fn().mockImplementation(() => ({
+    forceFlush: mockForceFlush,
+    getTracer: jest.fn(() => ({
+      startSpan: mockStartSpan,
+    })),
+    shutdown: mockShutdown,
+  })),
+}));
+
+describe('Langfuse callback composition', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('runs explicit per-agent tracing when callbacks is a CallbackManager', async () => {
+    const manager = CallbackManager.fromHandlers({
+      handleCustomEvent: async (): Promise<void> => undefined,
+    });
+    const run = await Run.create<t.IState>({
+      runId: 'test-langfuse-callback-manager',
+      graphConfig: {
+        type: 'standard',
+        agents: [
+          {
+            agentId: 'agent_abc123',
+            name: 'DWAINE',
+            provider: Providers.OPENAI,
+            clientOptions: { model: 'gpt-4' },
+            tools: [],
+            langfuse: {
+              enabled: true,
+              publicKey: 'pk-test',
+              secretKey: 'sk-test',
+            },
+          },
+        ],
+      },
+      skipCleanup: true,
+    });
+
+    run.Graph?.overrideTestModel(['hello']);
+
+    const config = {
+      callbacks: manager,
+      configurable: { thread_id: 'thread-1', user_id: 'user-1' },
+      streamMode: 'values' as const,
+      version: 'v2' as const,
+    };
+
+    await run.processStream({ messages: [new HumanMessage('hello')] }, config);
+
+    expect(mockStartSpan).toHaveBeenCalled();
+  });
+});

package/src/specs/langfuse-config.test.ts

@@ -1,15 +1,28 @@
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
+import { HumanMessage } from '@langchain/core/messages';
+import type { Serialized } from '@langchain/core/load/serializable';
 import { createLangfuseHandler } from '@/langfuse';
 
+const mockSpan = {
+  end: jest.fn(),
+  setAttributes: jest.fn(),
+  setStatus: jest.fn(),
+};
+const mockStartSpan = jest.fn(() => mockSpan);
+const mockGetTracer = jest.fn(() => ({
+  startSpan: mockStartSpan,
+}));
+
 jest.mock('@langfuse/otel', () => ({
   LangfuseSpanProcessor: jest.fn().mockImplementation(() => ({})),
+  isDefaultExportSpan: jest.fn(() => false),
 }));
 
 jest.mock('@opentelemetry/sdk-trace-base', () => ({
   BasicTracerProvider: jest.fn().mockImplementation(() => ({
     forceFlush: jest.fn(),
-    getTracer: jest.fn(),
+    getTracer: mockGetTracer,
     shutdown: jest.fn(),
   })),
 }));
@@ -42,6 +55,50 @@ describe('createLangfuseHandler', () => {
     expect(BasicTracerProvider).toHaveBeenCalledTimes(1);
   });
 
+  it('starts per-agent spans with v5 trace attributes', async () => {
+    const handler = createLangfuseHandler({
+      langfuse: {
+        enabled: true,
+        publicKey: 'pk-test',
+        secretKey: 'sk-test',
+      },
+      userId: 'user-1',
+      sessionId: 'thread-1',
+      traceMetadata: {
+        messageId: 'message-1',
+        agentId: 'agent-1',
+        agentName: 'DWAINE',
+      },
+      tags: ['librechat', 'agent'],
+    });
+
+    await handler?.handleChatModelStart(
+      {
+        id: ['langchain', 'chat_models', 'ChatOpenAI'],
+        kwargs: { model: 'gpt-4o' },
+      } as unknown as Serialized,
+      [[new HumanMessage('hello')]],
+      'run-1'
+    );
+
+    expect(mockGetTracer).toHaveBeenCalledWith('langfuse-sdk');
+    expect(mockStartSpan).toHaveBeenCalledWith(
+      'gpt-4o',
+      expect.objectContaining({
+        attributes: expect.objectContaining({
+          'langfuse.trace.name': 'LibreChat Agent: DWAINE',
+          'langfuse.trace.metadata.agentId': 'agent-1',
+          'langfuse.trace.metadata.messageId': 'message-1',
+          'langfuse.observation.model.name': 'gpt-4o',
+          'langfuse.observation.type': 'generation',
+          'user.id': 'user-1',
+          'session.id': 'thread-1',
+          'langfuse.trace.tags': ['librechat', 'agent'],
+        }),
+      })
+    );
+  });
+
   it('does not create a handler when a required key is missing', () => {
     const handler = createLangfuseHandler({
       langfuse: {

package/src/types/run.ts

@@ -3,10 +3,7 @@ import type * as z from 'zod';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { StructuredTool } from '@langchain/core/tools';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type {
-  BaseCallbackHandler,
-  CallbackHandlerMethods,
-} from '@langchain/core/callbacks/base';
+import type { Callbacks } from '@langchain/core/callbacks/manager';
 import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
@@ -213,9 +210,7 @@ export type RunConfig = {
   humanInTheLoop?: HumanInTheLoopConfig;
 };
 
-export type ProvidedCallbacks =
-  | (BaseCallbackHandler | CallbackHandlerMethods)[]
-  | undefined;
+export type ProvidedCallbacks = Callbacks | undefined;
 
 export type TokenCounter = (message: BaseMessage) => number;
 

package/src/utils/callbacks.ts

@@ -0,0 +1,39 @@
+import { ensureHandler } from '@langchain/core/callbacks/manager';
+import type {
+  BaseCallbackHandler,
+  CallbackHandlerMethods,
+} from '@langchain/core/callbacks/base';
+import type { Callbacks } from '@langchain/core/callbacks/manager';
+
+export type CallbackEntry = BaseCallbackHandler | CallbackHandlerMethods;
+
+export function appendCallbacks(
+  callbacks: Callbacks | undefined,
+  additions: readonly CallbackEntry[]
+): Callbacks {
+  if (additions.length === 0) {
+    return callbacks ?? [];
+  }
+
+  if (callbacks == null) {
+    return [...additions];
+  }
+
+  if (Array.isArray(callbacks)) {
+    return callbacks.concat(additions);
+  }
+
+  return callbacks.copy(additions.map(ensureHandler));
+}
+
+export function findCallback(
+  callbacks: Callbacks | undefined,
+  predicate: (callback: CallbackEntry) => boolean
+): CallbackEntry | undefined {
+  if (callbacks == null) {
+    return undefined;
+  }
+
+  const handlers = Array.isArray(callbacks) ? callbacks : callbacks.handlers;
+  return handlers.find(predicate);
+}