@librechat/agents 3.1.96 → 3.1.97

package/src/tools/__tests__/ToolNode.langfuse.test.ts

@@ -0,0 +1,41 @@
+const mockWithLangfuseToolOutputTracingConfig = jest.fn(
+  (_runLangfuse: unknown, action: () => unknown, _agentLangfuse: unknown) =>
+    action()
+);
+
+jest.mock('@/langfuseToolOutputTracing', () => ({
+  ...jest.requireActual('@/langfuseToolOutputTracing'),
+  withLangfuseToolOutputTracingConfig: mockWithLangfuseToolOutputTracingConfig,
+}));
+
+import { ToolNode } from '../ToolNode';
+
+describe('ToolNode Langfuse redaction context', () => {
+  beforeEach(() => {
+    mockWithLangfuseToolOutputTracingConfig.mockClear();
+  });
+
+  it('scopes ToolNode invocation with run and agent Langfuse config', async () => {
+    const runLangfuse = {
+      toolOutputTracing: { enabled: true },
+    };
+    const agentLangfuse = {
+      toolOutputTracing: { enabled: false },
+    };
+    const node = new ToolNode({
+      tools: [],
+      runLangfuse,
+      agentLangfuse,
+    });
+
+    await expect(node.invoke([])).rejects.toThrow(
+      'ToolNode only accepts AIMessages'
+    );
+
+    expect(mockWithLangfuseToolOutputTracingConfig).toHaveBeenCalledWith(
+      runLangfuse,
+      expect.any(Function),
+      agentLangfuse
+    );
+  });
+});

package/src/tools/subagent/SubagentExecutor.ts

@@ -213,6 +213,7 @@ export type SubagentExecutorOptions = {
   hookRegistry?: HookRegistry;
   parentRunId: string;
   parentAgentId?: string;
+  langfuse?: StandardGraphInput['langfuse'];
   tokenCounter?: TokenCounter;
   /** Remaining nesting budget. 0 or negative blocks execution. */
   maxDepth?: number;
@@ -243,6 +244,7 @@ export class SubagentExecutor {
   private readonly hookRegistry?: HookRegistry;
   private readonly parentRunId: string;
   private readonly parentAgentId?: string;
+  private readonly langfuse?: StandardGraphInput['langfuse'];
   private readonly tokenCounter?: TokenCounter;
   private readonly maxDepth: number;
   private readonly createChildGraph: ChildGraphFactory;
@@ -256,6 +258,7 @@ export class SubagentExecutor {
     this.hookRegistry = options.hookRegistry;
     this.parentRunId = options.parentRunId;
     this.parentAgentId = options.parentAgentId;
+    this.langfuse = options.langfuse;
     this.tokenCounter = options.tokenCounter;
     this.maxDepth = options.maxDepth ?? 1;
     this.createChildGraph = options.createChildGraph;
@@ -352,18 +355,20 @@ export class SubagentExecutor {
       runId: childRunId,
       signal: this.parentSignal,
       agents: [childInputs],
+      langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
     });
 
-    const forwarding = forwardingEnabled
-      ? this.createForwarderCallback({
+    let forwarding: ForwarderCallback | undefined;
+    if (forwardingEnabled) {
+      forwarding = this.createForwarderCallback({
         parentRegistry: parentRegistry!,
         subagentType,
         subagentAgentId: childAgentId,
         childRunId,
         parentToolCallId,
-      })
-      : undefined;
+      });
+    }
     const forwarder = forwarding?.handler;
 
     if (forwarder) {
@@ -444,7 +449,7 @@ export class SubagentExecutor {
       );
     } catch (error) {
       const errorMessage = truncateErrorMessage(error);
-      if (forwarder) {
+      if (forwarding) {
         await forwarding.drain();
         await this.emitSubagentUpdate(parentRegistry!, {
           childRunId,
@@ -491,7 +496,7 @@ export class SubagentExecutor {
       });
     }
 
-    if (forwarder) {
+    if (forwarding) {
       await forwarding.drain();
       await this.emitSubagentUpdate(parentRegistry!, {
         childRunId,

package/src/types/graph.ts

@@ -295,6 +295,7 @@ export type StandardGraphInput = {
   runId?: string;
   signal?: AbortSignal;
   agents: AgentInputs[];
+  langfuse?: LangfuseConfig;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
   calibrationRatio?: number;
@@ -408,11 +409,42 @@ export interface SubagentUpdateEvent {
   timestamp: string;
 }
 
+export type LangfuseToolOutputTracingConfig = {
+  /**
+   * Whether tool outputs should be exported to Langfuse. Defaults to
+   * `true`. Set to `false` to keep tool spans and redact their output.
+   */
+  enabled?: boolean;
+  /**
+   * Optional allowlist of tool names whose outputs should be redacted even
+   * when `enabled` is true.
+   */
+  redactedToolNames?: string[];
+  /**
+   * Match strategy for `redactedToolNames`. Defaults to `exact`; use
+   * `partial` to redact tools whose names contain a configured value.
+   */
+  redactedToolNameMatchMode?: 'exact' | 'partial';
+  /** Replacement text used for redacted tool outputs. */
+  redactionText?: string;
+};
+
+export type LangfuseToolNodeTracingConfig = {
+  /**
+   * Overrides ToolNode callback tracing. ToolNode spans are exported by the
+   * env-backed Langfuse callback, so this only enables tracing when that
+   * callback is configured.
+   */
+  enabled?: boolean;
+};
+
 export interface LangfuseConfig {
   enabled?: boolean;
   publicKey?: string;
   secretKey?: string;
   baseUrl?: string;
+  toolNodeTracing?: LangfuseToolNodeTracingConfig;
+  toolOutputTracing?: LangfuseToolOutputTracingConfig;
 }
 
 export interface AgentInputs {

package/src/types/run.ts

@@ -118,6 +118,12 @@ export type StandardGraphConfig = Omit<
 export type RunConfig = {
   runId: string;
   graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
+  /**
+   * Run-scoped Langfuse configuration. Per-agent `AgentInputs.langfuse`
+   * takes precedence for agent-specific spans; this object supplies defaults
+   * for run-wide tracing controls such as tool-output redaction.
+   */
+  langfuse?: g.LangfuseConfig;
   customHandlers?: Record<string, g.EventHandler>;
   /**
    * Pre-constructed hook registry for this run. Hooks fire at lifecycle

package/src/types/tools.ts

@@ -6,6 +6,7 @@ import type { HookRegistry } from '@/hooks';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { MessageContentComplex, ToolErrorData } from './stream';
 import type { HumanInTheLoopConfig } from './hitl';
+import type { LangfuseConfig } from './graph';
 
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
@@ -69,6 +70,12 @@ export type EagerEventToolCallChunkState = {
 export type ToolNodeOptions = {
   name?: string;
   tags?: string[];
+  /** Enables LangChain/LangGraph tracing for this ToolNode. Defaults to false. */
+  trace?: boolean;
+  /** Run-level Langfuse config used to scope ToolNode trace redaction. */
+  runLangfuse?: LangfuseConfig;
+  /** Agent-level Langfuse config used to scope ToolNode trace redaction. */
+  agentLangfuse?: LangfuseConfig;
   handleToolErrors?: boolean;
   loadRuntimeTools?: ToolRefGenerator;
   toolCallStepIds?: Map<string, string>;