@librechat/agents 3.2.35 → 3.2.37

package/src/agents/__tests__/AgentContext.test.ts

@@ -274,16 +274,11 @@ describe('AgentContext', () => {
         new HumanMessage('First'),
         new HumanMessage('Second'),
       ]);
-      const firstContent = result[1].content as TestSystemContentBlock[];
       const secondContent = result[2].content as TestSystemContentBlock[];
 
       expect(result).toHaveLength(3);
       expect(result[0].content).toBe('Dynamic only');
-      expect(firstContent[0]).toMatchObject({
-        type: 'text',
-        text: 'First',
-        cache_control: { type: 'ephemeral' },
-      });
+      expect(result[1].content).toBe('First');
       expect(secondContent[0]).toMatchObject({
         type: 'text',
         text: 'Second',
@@ -686,7 +681,7 @@ describe('AgentContext', () => {
       expect(result[8].content).toBe('Now answer without tools');
     });
 
-    it('adds OpenRouter body cache points when there is no dynamic tail', async () => {
+    it('adds a single OpenRouter body cache point on the tail when there is no dynamic tail', async () => {
       const ctx = createBasicContext({
         agentConfig: {
           provider: Providers.OPENROUTER,
@@ -702,9 +697,8 @@ describe('AgentContext', () => {
         new HumanMessage('First'),
         new HumanMessage('Second'),
       ]);
-      const firstContent = result[1].content as TestSystemContentBlock[];
       const secondContent = result[2].content as TestSystemContentBlock[];
-      expect(firstContent[0]).toHaveProperty('cache_control');
+      expect(result[1].content).toBe('First');
       expect(secondContent[0]).toHaveProperty('cache_control');
     });
 
@@ -2147,4 +2141,233 @@ describe('AgentContext', () => {
       expect(ctx.lastCallUsage!.inputTokens).toBe(8005);
     });
   });
+
+  describe('projectContextUsage', () => {
+    const countByChars = (msg: { content: unknown }): number => {
+      const content =
+        typeof msg.content === 'string'
+          ? msg.content
+          : JSON.stringify(msg.content);
+      return content.length;
+    };
+
+    const buildBranch = (
+      maxContextTokens: number,
+      perMessageTokens: number,
+      count: number,
+    ): { ctx: AgentContext; messages: AIMessage[] } => {
+      const ctx = createBasicContext({ tokenCounter: countByChars });
+      ctx.maxContextTokens = maxContextTokens;
+      const messages: AIMessage[] = [];
+      for (let i = 0; i < count; i++) {
+        // countByChars counts content length, and projectContextUsage recounts
+        // the supplied messages — so size content to the intended per-msg tokens.
+        const content = 'x'.repeat(perMessageTokens);
+        messages.push(
+          i % 2 === 0
+            ? (new HumanMessage(content) as unknown as AIMessage)
+            : new AIMessage(content),
+        );
+      }
+      return { ctx, messages };
+    };
+
+    it('returns null without a tokenizer or a window', () => {
+      const noCounter = createBasicContext({});
+      noCounter.maxContextTokens = 1000;
+      expect(noCounter.projectContextUsage([new HumanMessage('hi')])).toBeNull();
+
+      const noWindow = createBasicContext({ tokenCounter: countByChars });
+      noWindow.maxContextTokens = undefined;
+      expect(noWindow.projectContextUsage([new HumanMessage('hi')])).toBeNull();
+    });
+
+    it('keeps the whole branch and reports headroom when it fits', () => {
+      const { ctx, messages } = buildBranch(100_000, 1_000, 4);
+      const usage = ctx.projectContextUsage(messages);
+
+      expect(usage).not.toBeNull();
+      expect(usage!.breakdown.messageCount).toBe(4);
+      expect(usage!.breakdown.maxContextTokens).toBe(100_000);
+      expect(usage!.remainingContextTokens).toBeGreaterThan(0);
+      expect(usage!.breakdown.messageTokens).toBeGreaterThan(0);
+
+      const max = usage!.contextBudget ?? usage!.breakdown.maxContextTokens;
+      const used = max - (usage!.remainingContextTokens ?? 0);
+      expect(used).toBeLessThanOrEqual(max);
+    });
+
+    it('prunes older messages when the branch exceeds the window', () => {
+      const { ctx, messages } = buildBranch(3_000, 1_000, 6);
+      const usage = ctx.projectContextUsage(messages);
+
+      expect(usage).not.toBeNull();
+      expect(usage!.breakdown.messageCount).toBeGreaterThan(0);
+      expect(usage!.breakdown.messageCount).toBeLessThan(6);
+      expect(usage!.remainingContextTokens).toBeGreaterThanOrEqual(0);
+
+      const max = usage!.contextBudget ?? usage!.breakdown.maxContextTokens;
+      expect(max - (usage!.remainingContextTokens ?? 0)).toBeLessThanOrEqual(max);
+    });
+
+    it('does not mutate the context (local pruner, no field writes)', () => {
+      const { ctx, messages } = buildBranch(3_000, 1_000, 6);
+      const mapBefore = { ...ctx.indexTokenCountMap };
+
+      expect(ctx.pruneMessages).toBeUndefined();
+      ctx.projectContextUsage(messages);
+
+      expect(ctx.pruneMessages).toBeUndefined();
+      expect(ctx.indexTokenCountMap).toEqual(mapBefore);
+    });
+
+    it('does not mutate the caller messages under context pressure', () => {
+      const ctx = createBasicContext({ tokenCounter: countByChars });
+      ctx.maxContextTokens = 400;
+      const consumed = new ToolMessage({
+        content: 'x'.repeat(20_000),
+        tool_call_id: 't1',
+        name: 'tool',
+      });
+      const messages: AIMessage[] = [
+        new HumanMessage('question') as unknown as AIMessage,
+        new AIMessage({
+          content: '',
+          tool_calls: [{ id: 't1', name: 'tool', args: {} }],
+        }),
+        consumed as unknown as AIMessage,
+        new AIMessage('final answer'),
+      ];
+      const originalRef = messages[2];
+      const originalContent = (messages[2] as unknown as ToolMessage).content;
+
+      ctx.projectContextUsage(messages);
+
+      expect(messages[2]).toBe(originalRef);
+      expect((messages[2] as unknown as ToolMessage).content).toBe(
+        originalContent,
+      );
+    });
+
+    it('recounts the supplied branch, ignoring a stale context token map', () => {
+      const ctx = createBasicContext({ tokenCounter: countByChars });
+      ctx.maxContextTokens = 3_000;
+      // Empty/stale map — if it were reused, every message would count as 0 and
+      // nothing would prune. The fresh recount must drive pruning instead.
+      ctx.indexTokenCountMap = {};
+      const messages: AIMessage[] = [];
+      for (let i = 0; i < 6; i++) {
+        messages.push(new HumanMessage('x'.repeat(1_000)) as unknown as AIMessage);
+      }
+
+      const usage = ctx.projectContextUsage(messages);
+
+      expect(usage).not.toBeNull();
+      expect(usage!.breakdown.messageCount).toBeLessThan(6);
+    });
+
+    it('uses a caller-supplied token map when provided', () => {
+      const { ctx, messages } = buildBranch(3_000, 1, 6);
+      // Each message is ~1 char, so a recount would fit all 6. The supplied map
+      // claims 1000 each, forcing a prune — proving the map is honored.
+      const indexTokenCountMap: Record<string, number> = {};
+      for (let i = 0; i < messages.length; i++) {
+        indexTokenCountMap[String(i)] = 1_000;
+      }
+
+      const usage = ctx.projectContextUsage(messages, { indexTokenCountMap });
+
+      expect(usage!.breakdown.messageCount).toBeLessThan(6);
+    });
+
+    it('ignores this context live usage so projections are not recalibrated', () => {
+      const build = (): { ctx: AgentContext; messages: AIMessage[] } => {
+        const ctx = createBasicContext({ tokenCounter: countByChars });
+        ctx.maxContextTokens = 5_000;
+        const messages: AIMessage[] = [0, 1, 2].map(
+          () => new HumanMessage('x'.repeat(1_000)) as unknown as AIMessage,
+        );
+        return { ctx, messages };
+      };
+
+      const clean = build();
+      const cleanUsage = clean.ctx.projectContextUsage(clean.messages);
+
+      const dirty = build();
+      dirty.ctx.currentUsage = {
+        input_tokens: 4_000,
+        output_tokens: 50,
+        total_tokens: 4_050,
+      };
+      dirty.ctx.updateLastCallUsage({ input_tokens: 4_000, output_tokens: 50 });
+      const dirtyUsage = dirty.ctx.projectContextUsage(dirty.messages);
+
+      expect(dirtyUsage!.remainingContextTokens).toBe(
+        cleanUsage!.remainingContextTokens,
+      );
+      expect(dirtyUsage!.calibrationRatio).toBe(cleanUsage!.calibrationRatio);
+    });
+
+    it('does not mutate AI message content arrays during projection', () => {
+      const ctx = createBasicContext({
+        agentConfig: {
+          provider: Providers.ANTHROPIC,
+          clientOptions: {
+            model: 'claude-x',
+            thinking: { type: 'enabled', budget_tokens: 1024 },
+          } as never,
+        },
+        tokenCounter: countByChars,
+      });
+      ctx.maxContextTokens = 2_000;
+      const aiContent = [
+        { type: 'thinking', thinking: 'step by step', signature: 'sig' },
+        { type: 'text', text: 'the answer' },
+      ];
+      const ai = new AIMessage({ content: aiContent as never });
+      const messages: AIMessage[] = [
+        new HumanMessage('question') as unknown as AIMessage,
+        ai,
+        new HumanMessage('another') as unknown as AIMessage,
+      ];
+      const contentRef = ai.content;
+      const lenBefore = (ai.content as unknown[]).length;
+
+      ctx.projectContextUsage(messages);
+
+      expect(messages[1].content).toBe(contentRef);
+      expect((messages[1].content as unknown[]).length).toBe(lenBefore);
+    });
+
+    it('honors an explicit calibrationRatio seed', () => {
+      const base = buildBranch(100_000, 1_000, 4);
+      const baseUsage = base.ctx.projectContextUsage(base.messages);
+
+      const scaled = buildBranch(100_000, 1_000, 4);
+      const scaledUsage = scaled.ctx.projectContextUsage(scaled.messages, {
+        calibrationRatio: 3,
+      });
+
+      expect(scaledUsage!.calibrationRatio).toBe(3);
+      expect(scaledUsage!.remainingContextTokens).not.toBe(
+        baseUsage!.remainingContextTokens,
+      );
+    });
+
+    it('refreshes a stale system runnable before projecting', () => {
+      const ctx = createBasicContext({
+        agentConfig: { instructions: 'system prompt' },
+        tokenCounter: countByChars,
+      });
+      ctx.maxContextTokens = 5_000;
+      ctx.initializeSystemRunnable();
+      const systemBefore = ctx.systemMessageTokens;
+
+      // Adds a handoff preamble + marks stale, but defers the token recount.
+      ctx.setHandoffContext('PriorAgent', ['SiblingA', 'SiblingB']);
+      ctx.projectContextUsage([new HumanMessage('hi') as unknown as AIMessage]);
+
+      expect(ctx.systemMessageTokens).toBeGreaterThan(systemBefore);
+    });
+  });
 });

package/src/agents/__tests__/projection.test.ts

@@ -0,0 +1,73 @@
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+import { projectAgentContextUsage } from '../projection';
+
+const countByChars = (msg: { content: unknown }): number => {
+  const content =
+    typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+  return content.length;
+};
+
+const agent = (maxContextTokens: number): t.AgentInputs => ({
+  agentId: 'test-agent',
+  provider: Providers.OPENAI,
+  instructions: 'system prompt',
+  maxContextTokens,
+});
+
+const branch = (perMessageChars: number, count: number): AIMessage[] => {
+  const messages: AIMessage[] = [];
+  for (let i = 0; i < count; i++) {
+    const content = 'x'.repeat(perMessageChars);
+    messages.push(
+      i % 2 === 0
+        ? (new HumanMessage(content) as unknown as AIMessage)
+        : new AIMessage(content),
+    );
+  }
+  return messages;
+};
+
+describe('projectAgentContextUsage', () => {
+  it('returns a budget snapshot for a branch that fits', async () => {
+    const usage = await projectAgentContextUsage({
+      agent: agent(100_000),
+      messages: branch(1_000, 4),
+      tokenCounter: countByChars,
+    });
+
+    expect(usage).not.toBeNull();
+    expect(usage!.breakdown.maxContextTokens).toBe(100_000);
+    expect(usage!.breakdown.messageCount).toBe(4);
+    expect(usage!.remainingContextTokens).toBeGreaterThan(0);
+    expect(usage!.agentId).toBe('test-agent');
+  });
+
+  it('prunes when the branch exceeds the window', async () => {
+    const usage = await projectAgentContextUsage({
+      agent: agent(3_000),
+      messages: branch(1_000, 6),
+      tokenCounter: countByChars,
+    });
+
+    expect(usage).not.toBeNull();
+    expect(usage!.breakdown.messageCount).toBeGreaterThan(0);
+    expect(usage!.breakdown.messageCount).toBeLessThan(6);
+  });
+
+  it('returns null without a context window', async () => {
+    const noWindow: t.AgentInputs = {
+      agentId: 'test-agent',
+      provider: Providers.OPENAI,
+      instructions: 'sys',
+    };
+    const usage = await projectAgentContextUsage({
+      agent: noWindow,
+      messages: branch(100, 2),
+      tokenCounter: countByChars,
+    });
+
+    expect(usage).toBeNull();
+  });
+});

package/src/agents/projection.ts

@@ -0,0 +1,46 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { AgentContext } from './AgentContext';
+
+export interface ProjectAgentContextUsageParams {
+  /** Same `AgentInputs` a run is built from (instructions, tools, model, window). */
+  agent: t.AgentInputs;
+  /** Branch messages to project, in send order (no leading system message). */
+  messages: BaseMessage[];
+  tokenCounter: t.TokenCounter;
+  /** Per-message counts aligned to `messages` (e.g. from `formatAgentMessages`).
+   *  When omitted, counts are recounted via `tokenCounter`. */
+  indexTokenCountMap?: Record<string, number>;
+  /** Provider-calibrated ratio from a prior snapshot, applied as a static seed. */
+  calibrationRatio?: number;
+  runId?: string;
+  agentId?: string;
+}
+
+/**
+ * Projects a pre-send context-usage snapshot for a branch under an agent config
+ * WITHOUT invoking the model — the host-side (page-load / branch-switch /
+ * window-switch) counterpart to the live `ON_CONTEXT_USAGE` event. Builds a
+ * throwaway `AgentContext` from the same `AgentInputs` a run uses, awaits its
+ * instruction/tool token accounting, then runs the shared pruner + budget math
+ * via `AgentContext.projectContextUsage` (which never mutates the supplied
+ * messages). Returns null when the config has no tokenizer or context window.
+ */
+export async function projectAgentContextUsage({
+  agent,
+  messages,
+  tokenCounter,
+  indexTokenCountMap,
+  calibrationRatio,
+  runId,
+  agentId,
+}: ProjectAgentContextUsageParams): Promise<t.ContextUsageEvent | null> {
+  const context = AgentContext.fromConfig(agent, tokenCounter, indexTokenCountMap);
+  await context.tokenCalculationPromise;
+  return context.projectContextUsage(messages, {
+    runId,
+    agentId: agentId ?? agent.agentId,
+    calibrationRatio,
+    indexTokenCountMap,
+  });
+}

package/src/graphs/Graph.ts

@@ -19,13 +19,14 @@ import {
   convertMessagesToContent,
   sanitizeOrphanToolBlocks,
   extractToolDiscoveries,
-  addBedrockCacheControl,
+  addBedrockTailCacheControl,
   formatArtifactPayload,
   enforceOriginalContentCap,
   formatContentStrings,
   isLegacyConvertible,
   createPruneMessages,
-  addCacheControl,
+  syncBudgetDerivedFields,
+  addTailCacheControl,
   getMessageId,
   makeIsDeferred,
   partitionAndMarkAnthropicToolCache,
@@ -111,35 +112,6 @@ function trailingMutationStart(messages: BaseMessage[]): number {
   return Math.max(0, Math.min(index, messages.length - 2));
 }
 
-/**
- * Re-derives the breakdown fields coupled to the calibrated budget math so
- * the snapshot stays internally consistent: the aggregate
- * `instructionTokens`/`availableForMessages` reflect the pruner's effective
- * (calibrated) overhead — component fields remain local estimates — and
- * `messageTokens` mirrors `contextBudget - instructions - remaining`.
- */
-function syncBudgetDerivedFields(usage: t.ContextUsageEvent): void {
-  const { breakdown, contextBudget, effectiveInstructionTokens } = usage;
-  if (effectiveInstructionTokens == null) {
-    return;
-  }
-  breakdown.instructionTokens = effectiveInstructionTokens;
-  if (contextBudget == null) {
-    return;
-  }
-  breakdown.availableForMessages = Math.max(
-    0,
-    contextBudget - effectiveInstructionTokens
-  );
-  if (usage.remainingContextTokens == null) {
-    return;
-  }
-  breakdown.messageTokens = Math.max(
-    0,
-    contextBudget - effectiveInstructionTokens - usage.remainingContextTokens
-  );
-}
-
 type ReasoningKey = 'reasoning_content' | 'reasoning';
 type ReasoningSummary = { summary?: Array<{ text?: string }> };
 type ReasoningDetail = { type?: string; text?: string };
@@ -1761,35 +1733,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
       }
 
-      if (agentContext.provider === Providers.ANTHROPIC) {
-        const anthropicOptions = agentContext.clientOptions as
-          | t.AnthropicClientOptions
-          | undefined;
-        if (
-          anthropicOptions?.promptCache === true &&
-          !agentContext.systemRunnable
-        ) {
-          finalMessages = addCacheControl<BaseMessage>(finalMessages);
-        }
-      } else if (agentContext.provider === Providers.BEDROCK) {
-        const bedrockOptions = agentContext.clientOptions as
-          | t.BedrockAnthropicClientOptions
-          | undefined;
-        if (bedrockOptions?.promptCache === true) {
-          finalMessages = addBedrockCacheControl<BaseMessage>(finalMessages);
-        }
-      } else if (agentContext.provider === Providers.OPENROUTER) {
-        const openRouterOptions = agentContext.clientOptions as
-          | t.ProviderOptionsMap[Providers.OPENROUTER]
-          | undefined;
-        if (
-          openRouterOptions?.promptCache === true &&
-          !agentContext.systemRunnable
-        ) {
-          finalMessages = addCacheControl<BaseMessage>(finalMessages);
-        }
-      }
-
       if (
         isThinkingEnabled(agentContext.provider, agentContext.clientOptions)
       ) {
@@ -1811,13 +1754,53 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         );
       }
 
-      // Intentionally broad: runs when the pruner wasn't used OR any post-pruning
-      // transform (addCacheControl, ensureThinkingBlock, etc.) reassigned finalMessages.
-      // sanitizeOrphanToolBlocks fast-paths to a Set diff check when no orphans exist,
-      // so the cost is negligible and this acts as a safety net for Anthropic/Bedrock.
+      // Determine the prompt-cache strategy up front. Two distinct facts:
+      //
+      //   `providerPromptCacheEnabled` — prompt caching is on for this provider
+      //   at all. This drives orphan cleanup, because EVERY cached send must be
+      //   sanitized — including the system-runnable path, where AgentContext (not
+      //   this node) adds the body marker.
+      //
+      //   `willAddTailCache` — THIS node will add the marker itself. Anthropic /
+      //   OpenRouter defer to the system runnable when one owns the system-prompt
+      //   breakpoint, so they exclude that case; Bedrock always marks here.
+      const anthropicPromptCacheEnabled =
+        agentContext.provider === Providers.ANTHROPIC &&
+        (agentContext.clientOptions as t.AnthropicClientOptions | undefined)
+          ?.promptCache === true;
+      const openRouterPromptCacheEnabled =
+        agentContext.provider === Providers.OPENROUTER &&
+        (
+          agentContext.clientOptions as
+            | t.ProviderOptionsMap[Providers.OPENROUTER]
+            | undefined
+        )?.promptCache === true;
+      const bedrockPromptCacheEnabled =
+        agentContext.provider === Providers.BEDROCK &&
+        (
+          agentContext.clientOptions as
+            | t.BedrockAnthropicClientOptions
+            | undefined
+        )?.promptCache === true;
+      const providerPromptCacheEnabled =
+        anthropicPromptCacheEnabled ||
+        openRouterPromptCacheEnabled ||
+        bedrockPromptCacheEnabled;
+
+      // Intentionally broad: runs when the pruner wasn't used, when any
+      // post-pruning transform (ensureThinkingBlock, etc.) reassigned
+      // finalMessages, OR when this is a prompt-cached send. The last clause
+      // matters because the marker is now applied AFTER this gate (and, for the
+      // system-runnable path, in AgentContext entirely): without it, a cached
+      // send whose pruner returned the context unchanged would skip cleanup and
+      // could ship orphaned AI/tool pairs from persisted history.
+      // sanitizeOrphanToolBlocks fast-paths to a Set diff check when no orphans
+      // exist, so the cost is negligible.
       const needsOrphanSanitize =
         anthropicLike &&
-        (!agentContext.pruneMessages || finalMessages !== messagesToUse);
+        (!agentContext.pruneMessages ||
+          finalMessages !== messagesToUse ||
+          providerPromptCacheEnabled);
       if (needsOrphanSanitize) {
         const beforeSanitize = finalMessages.length;
         finalMessages = sanitizeOrphanToolBlocks(finalMessages);
@@ -1837,6 +1820,24 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
       }
 
+      // Place the single tail prompt-cache breakpoint LAST, after thinking
+      // normalization and orphan sanitization. ensureThinkingBlockInMessages can
+      // fold a trailing non-thinking AI→Tool chain into a `[Previous agent
+      // context]` HumanMessage whose builder copies text but not cache_control /
+      // cachePoint, and sanitizeOrphanToolBlocks can drop the anchored block — so
+      // marking earlier would let the only breakpoint vanish before the model
+      // call (zero message caching). Anchoring on the final message list keeps
+      // the marker on a block that actually ships. The system-runnable path
+      // adds its body marker in AgentContext, so this node skips it there.
+      if (
+        (anthropicPromptCacheEnabled || openRouterPromptCacheEnabled) &&
+        !agentContext.systemRunnable
+      ) {
+        finalMessages = addTailCacheControl<BaseMessage>(finalMessages);
+      } else if (bedrockPromptCacheEnabled) {
+        finalMessages = addBedrockTailCacheControl<BaseMessage>(finalMessages);
+      }
+
       if (
         agentContext.lastStreamCall != null &&
         agentContext.streamBuffer != null

package/src/index.ts

@@ -8,6 +8,9 @@ export * from './messages';
 /* Graphs */
 export * from './graphs';
 
+/* Context-usage projection (host-side pre-send snapshot) */
+export * from './agents/projection';
+
 /* Summarization */
 export * from './summarization';
 

package/src/langfuse.ts

@@ -11,6 +11,7 @@ const TRACE_METADATA_MAX_LENGTH = 200;
 const LANGFUSE_FORCE_FLUSH_ON_DISPOSE = 'LANGFUSE_FORCE_FLUSH_ON_DISPOSE';
 
 export type LangfuseTraceMetadata = Record<string, string>;
+type LangfuseMetadata = NonNullable<t.LangfuseConfig['metadata']>;
 
 type LangfuseHandlerParams = {
   userId?: string;
@@ -44,6 +45,13 @@ function hasLangfuseTracingConfig(langfuse?: t.LangfuseConfig): boolean {
   );
 }
 
+function hasLangfuseTraceAttributes(langfuse?: t.LangfuseConfig): boolean {
+  return (
+    Object.keys(createTraceMetadata(langfuse?.metadata ?? {})).length > 0 ||
+    (mergeLangfuseTags(undefined, langfuse?.tags)?.length ?? 0) > 0
+  );
+}
+
 export function hasLangfuseConfigCredentials(
   langfuse?: t.LangfuseConfig
 ): langfuse is t.LangfuseConfig & {
@@ -67,6 +75,7 @@ export function isExplicitLangfuseConfig(langfuse?: t.LangfuseConfig): boolean {
     isPresent(langfuse?.publicKey) ||
     isPresent(langfuse?.secretKey) ||
     isPresent(langfuse?.baseUrl) ||
+    hasLangfuseTraceAttributes(langfuse) ||
     hasLangfuseTracingConfig(langfuse)
   );
 }
@@ -110,6 +119,27 @@ export function createLangfuseTraceMetadata({
   });
 }
 
+function mergeLangfuseTraceMetadata(
+  traceMetadata?: LangfuseTraceMetadata,
+  metadata?: LangfuseMetadata
+): LangfuseTraceMetadata | undefined {
+  const merged = createTraceMetadata({
+    ...(metadata ?? {}),
+    ...(traceMetadata ?? {}),
+  });
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+function mergeLangfuseTags(
+  tags?: string[],
+  configTags?: string[]
+): string[] | undefined {
+  const merged = [...(tags ?? []), ...(configTags ?? [])].filter(
+    (tag) => tag.trim() !== ''
+  );
+  return merged.length > 0 ? [...new Set(merged)] : undefined;
+}
+
 export function getLangfuseTraceName(
   traceMetadata?: LangfuseTraceMetadata,
   fallback: string = 'LibreChat Agent'
@@ -161,12 +191,16 @@ export function createLangfuseHandler({
   return new CallbackHandler({
     userId,
     sessionId,
-    traceMetadata,
-    tags,
+    traceMetadata: mergeLangfuseTraceMetadata(
+      traceMetadata,
+      langfuse?.metadata
+    ),
+    tags: mergeLangfuseTags(tags, langfuse?.tags),
   });
 }
 
 function createPropagateAttributeParams({
+  langfuse,
   userId,
   sessionId,
   traceMetadata,
@@ -177,8 +211,8 @@ function createPropagateAttributeParams({
     userId,
     sessionId,
     traceName,
-    tags,
-    metadata: traceMetadata,
+    tags: mergeLangfuseTags(tags, langfuse?.tags),
+    metadata: mergeLangfuseTraceMetadata(traceMetadata, langfuse?.metadata),
   };
 }
 

package/src/langfuseToolOutputTracing.ts

@@ -692,10 +692,28 @@ export function resolveLangfuseConfig(
         ...agentLangfuse.toolOutputTracing,
       }
       : undefined;
+  const metadata =
+    runLangfuse.metadata != null || agentLangfuse.metadata != null
+      ? {
+        ...runLangfuse.metadata,
+        ...agentLangfuse.metadata,
+      }
+      : undefined;
+  const tags =
+    runLangfuse.tags != null || agentLangfuse.tags != null
+      ? [
+        ...new Set([
+          ...(runLangfuse.tags ?? []),
+          ...(agentLangfuse.tags ?? []),
+        ]),
+      ]
+      : undefined;
 
   return {
     ...runLangfuse,
     ...agentLangfuse,
+    ...(metadata != null ? { metadata } : {}),
+    ...(tags != null ? { tags } : {}),
     ...(toolNodeTracing != null ? { toolNodeTracing } : {}),
     ...(toolOutputTracing != null ? { toolOutputTracing } : {}),
   };