@librechat/agents 3.6.7 → 3.6.8

package/src/langfuseTraceShaping.ts

@@ -1,9 +1,21 @@
 import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { Constants } from '@/common';
+import {
+  Constants,
+  STANDARD_GRAPH_RUN_NAME,
+  MULTI_AGENT_GRAPH_RUN_NAME,
+  AGENT_MODEL_CALL_RUN_NAME,
+  ACTIVITY_LABEL_RUN_NAME,
+  REASONING_LABEL_RUN_NAME,
+  ACTIVITY_PHASE_RUN_NAME,
+  ACTIVITY_PHASE_LABEL_RUN_NAME,
+} from '@/common';
+import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 
 const LANGGRAPH_START_NODE = '__start__';
+const LANGGRAPH_RUN_NAME = 'LangGraph';
 const ANONYMOUS_LAMBDA_NAME = 'RunnableLambda';
+const RUNNABLE_SEQUENCE_NAME = 'RunnableSequence';
 const LANGGRAPH_AGENT_NODE_PREFIX = 'agent=';
 const LANGGRAPH_TOOL_NODE_PREFIX = 'tools=';
 const AGENT_NODE_SPAN_NAME = 'agent';
@@ -14,11 +26,15 @@ const CHAIN_OBSERVATION_TYPE = 'chain';
 const TOOL_OBSERVATION_TYPE = 'tool';
 const AGENT_TRACE_TAG = 'agent';
 const TITLE_TRACE_TAG = 'title';
+const ACTIVITY_LABEL_TRACE_TAG = 'activity-label';
+const REASONING_LABEL_TRACE_TAG = 'reasoning-label';
 const ACTIVITY_PHASE_TRACE_TAG = 'activity-phase';
-const ACTIVITY_PHASE_ROOT_NAME = 'summarize-activity-phase';
 const EPHEMERAL_AGENT_SENDER_SEPARATOR = '___';
 const EPHEMERAL_AGENT_INDEX_SEPARATOR = '____';
+const DEPRECATED_TRACE_INPUT_ATTRIBUTE = 'langfuse.trace.input';
+const DEPRECATED_TRACE_OUTPUT_ATTRIBUTE = 'langfuse.trace.output';
 const OBSERVATION_METADATA_LANGGRAPH_NODE = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langgraph_node`;
+const OBSERVATION_METADATA_OPERATION = `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.${LANGFUSE_OPERATION_METADATA_KEY}`;
 
 type MutableSpan = ReadableSpan & {
   name: string;
@@ -192,9 +208,7 @@ function getMessageToolCalls(
  */
 /** Tool-result ids present in the serialized state — ToolNode's
  *  `!toolMessageIds.has(id)` execution filter, mirrored for the span. */
-function getToolResultIds(
-  messages: Record<string, unknown>[]
-): Set<string> {
+function getToolResultIds(messages: Record<string, unknown>[]): Set<string> {
   const ids = new Set<string>();
   for (const message of messages) {
     if (getMessageRole(message) !== 'tool') {
@@ -217,7 +231,9 @@ function getMessageInvalidToolCalls(
 ): SerializedToolCall[] {
   const rawCalls =
     message.invalid_tool_calls ??
-    (isRecord(message.kwargs) ? message.kwargs.invalid_tool_calls : undefined) ??
+    (isRecord(message.kwargs)
+      ? message.kwargs.invalid_tool_calls
+      : undefined) ??
     (isRecord(message.data) ? message.data.invalid_tool_calls : undefined);
   if (!Array.isArray(rawCalls)) {
     return [];
@@ -345,7 +361,80 @@ function shapeAgentNodeSpan(span: MutableSpan): void {
     ROOT_OBSERVATION_TYPE;
 }
 
-function shapeRootSpan(span: MutableSpan): void {
+function shapeGraphSpan(span: MutableSpan): void {
+  if (span.name === LANGGRAPH_RUN_NAME) {
+    span.name = STANDARD_GRAPH_RUN_NAME;
+  }
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    ROOT_OBSERVATION_TYPE;
+}
+
+function isAgentModelCallSpan(span: MutableSpan): boolean {
+  if (
+    span.name !== RUNNABLE_SEQUENCE_NAME &&
+    span.name !== AGENT_MODEL_CALL_RUN_NAME
+  ) {
+    return false;
+  }
+  const node = span.attributes[OBSERVATION_METADATA_LANGGRAPH_NODE];
+  return (
+    typeof node === 'string' && node.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)
+  );
+}
+
+function shapeAgentModelCallSpan(span: MutableSpan): void {
+  span.name = AGENT_MODEL_CALL_RUN_NAME;
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    CHAIN_OBSERVATION_TYPE;
+}
+
+function shapeActivityPhaseSpan(span: MutableSpan): void {
+  span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
+    CHAIN_OBSERVATION_TYPE;
+}
+
+function shapeGenerationSpan(span: MutableSpan): void {
+  if (
+    hasTraceTag(span, ACTIVITY_LABEL_TRACE_TAG) &&
+    span.attributes[OBSERVATION_METADATA_OPERATION] === ACTIVITY_LABEL_RUN_NAME
+  ) {
+    span.name = ACTIVITY_LABEL_RUN_NAME;
+    return;
+  }
+  if (
+    hasTraceTag(span, REASONING_LABEL_TRACE_TAG) &&
+    span.attributes[OBSERVATION_METADATA_OPERATION] === REASONING_LABEL_RUN_NAME
+  ) {
+    span.name = REASONING_LABEL_RUN_NAME;
+    return;
+  }
+  if (
+    hasTraceTag(span, ACTIVITY_PHASE_TRACE_TAG) &&
+    span.attributes[OBSERVATION_METADATA_OPERATION] ===
+      ACTIVITY_PHASE_LABEL_RUN_NAME
+  ) {
+    span.name = ACTIVITY_PHASE_LABEL_RUN_NAME;
+    return;
+  }
+  span.name = GENERATION_SPAN_NAME;
+}
+
+function isGraphSpan(span: MutableSpan): boolean {
+  if (
+    span.name !== LANGGRAPH_RUN_NAME &&
+    span.name !== STANDARD_GRAPH_RUN_NAME &&
+    span.name !== MULTI_AGENT_GRAPH_RUN_NAME
+  ) {
+    return false;
+  }
+  return (
+    isRootSpan(span) ||
+    typeof span.attributes[OBSERVATION_METADATA_LANGGRAPH_NODE] === 'string' ||
+    hasTraceTag(span, AGENT_TRACE_TAG)
+  );
+}
+
+function shapeConversationPayload(span: MutableSpan): void {
   const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
   const outputKey = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
   const question = findLastMessageText(
@@ -361,8 +450,7 @@ function shapeRootSpan(span: MutableSpan): void {
    *  observation carrying its own prompt: reducing its observation input
    *  would discard the SystemMessage from the one place it is traced.
    *  Chain/agent roots keep the full reduction; their child generations
-   *  still record the complete prompt. Trace-level input/output reduce
-   *  either way, so the trace list keeps showing question and answer. */
+   *  still record the complete prompt. */
   if (!isGenerationSpan(span)) {
     if (question != null) {
       span.attributes[inputKey] = question;
@@ -371,14 +459,6 @@ function shapeRootSpan(span: MutableSpan): void {
       span.attributes[outputKey] = answer;
     }
   }
-  const traceInput = question ?? span.attributes[inputKey];
-  const traceOutput = answer ?? span.attributes[outputKey];
-  if (traceInput != null) {
-    span.attributes[LangfuseOtelSpanAttributes.TRACE_INPUT] = traceInput;
-  }
-  if (traceOutput != null) {
-    span.attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT] = traceOutput;
-  }
 }
 
 function isGenerationSpan(span: MutableSpan): boolean {
@@ -477,7 +557,7 @@ function shapeRootObservationType(span: MutableSpan): void {
   }
   if (
     hasTraceTag(span, TITLE_TRACE_TAG) ||
-    (span.name === ACTIVITY_PHASE_ROOT_NAME &&
+    (span.name === ACTIVITY_PHASE_RUN_NAME &&
       hasTraceTag(span, ACTIVITY_PHASE_TRACE_TAG))
   ) {
     span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_TYPE] =
@@ -496,32 +576,46 @@ function shapeRootObservationType(span: MutableSpan): void {
  *   (`provider__model`) — strip it so switching models doesn't break
  *   name-based logic (item 1). The outer workflow node is named with the
  *   bare agent id; ephemeral ids reduce to their stable sender name.
+ * - Graph and prompt-to-model framework names become stable SDK operations:
+ *   `AgentGraph` / `MultiAgentGraph` and `AgentModelCall`.
  * - LLM generation spans keep the provider client class name (`ChatOpenAI`,
- *   `AzureChatOpenAI`, …); rename them to a provider-agnostic `llm` so the
- *   name reflects the operation, not the model (the model stays on the
- *   generation's model attribute).
+ *   `AzureChatOpenAI`, …); rename ordinary calls to a provider-agnostic `llm`
+ *   and label calls by their activity/reasoning role. The model stays on the
+ *   generation's model attribute.
  * - Agent nodes become `agent` observations, while tool-dispatch nodes become
  *   stable `chain` observations whose input is scoped to the pending calls.
  *   Individual child calls remain `tool` observations (items 3 & 4).
  * - Agent trace roots become `agent` observations, while title and activity
- *   summary roots become `chain` observations. Root and trace input/output are
- *   reduced to the user question and assistant response when chat messages are
- *   available (item 2).
+ *   summary operations become `chain` observations. Root-observation
+ *   input/output are reduced to the user question and assistant response when
+ *   chat messages are available (item 2).
  */
 export function shapeLangfuseSpan(span: ReadableSpan): void {
   const mutable = span as MutableSpan;
+  delete mutable.attributes[DEPRECATED_TRACE_INPUT_ATTRIBUTE];
+  delete mutable.attributes[DEPRECATED_TRACE_OUTPUT_ATTRIBUTE];
+  const isGraphObservation = isGraphSpan(mutable);
   if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
     shapeAgentNodeSpan(mutable);
   } else if (mutable.name.startsWith(LANGGRAPH_TOOL_NODE_PREFIX)) {
     shapeToolNodeSpan(mutable);
+  } else if (isGraphObservation) {
+    shapeGraphSpan(mutable);
+  } else if (isAgentModelCallSpan(mutable)) {
+    shapeAgentModelCallSpan(mutable);
+  } else if (mutable.name === ACTIVITY_PHASE_RUN_NAME) {
+    shapeActivityPhaseSpan(mutable);
   } else if (isGenerationSpan(mutable)) {
-    mutable.name = GENERATION_SPAN_NAME;
+    shapeGenerationSpan(mutable);
   } else {
     shapeEphemeralAgentNodeSpan(mutable);
   }
   if (!isRootSpan(span)) {
+    if (isGraphObservation) {
+      shapeConversationPayload(mutable);
+    }
     return;
   }
   shapeRootObservationType(mutable);
-  shapeRootSpan(mutable);
+  shapeConversationPayload(mutable);
 }

package/src/llm/openai/index.ts

@@ -58,14 +58,14 @@ import {
   STREAMED_TOOL_CALL_ADAPTER_METADATA_KEY,
   OPENAI_CHAT_SEQUENTIAL_STREAMED_TOOL_CALL_ADAPTER,
 } from '@/tools/streamedToolCallSeals';
-import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
-import { INTENT_ARG, isIntentLabelProperty } from '@/tools/intentArg';
-import { smoothStream, resolveStreamDelay } from '@/llm/stream/smoother';
 import {
   hasReasoningKwargs,
   hasToolCallChunks,
   getReasoningKwargsText,
 } from '@/llm/stream/chunkAdapters';
+import { isReasoningModel, _convertMessagesToOpenAIParams } from './utils';
+import { smoothStream, resolveStreamDelay } from '@/llm/stream/smoother';
+import { INTENT_ARG, isIntentLabelProperty } from '@/tools/intentArg';
 import { dropRepeatedScalarMetadata } from './streamMetadata';
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -919,6 +919,33 @@ function attachResponsesReplayPosition(
   chunk.message.lc_kwargs.additional_kwargs = additionalKwargs;
 }
 
+function getResponsesStreamError(
+  event: OpenAIClient.Responses.ResponseStreamEvent
+): Error | undefined {
+  if (event.type === 'error') {
+    return new OpenAIClient.APIError(
+      undefined,
+      event,
+      event.message,
+      undefined
+    );
+  }
+  if (event.type !== 'response.failed') {
+    return;
+  }
+  if (event.response.error != null) {
+    return new OpenAIClient.APIError(
+      undefined,
+      event.response.error,
+      event.response.error.message,
+      undefined
+    );
+  }
+  return new OpenAIClient.OpenAIError(
+    `Response ${event.response.id} failed without error details.`
+  );
+}
+
 async function* convertLibreChatResponsesStream(
   stream: AsyncIterable<OpenAIClient.Responses.ResponseStreamEvent>,
   options: ResponsesStreamChunkOptions,
@@ -929,6 +956,10 @@ async function* convertLibreChatResponsesStream(
   try {
     for await (const event of stream) {
       options.signal?.throwIfAborted();
+      const streamError = getResponsesStreamError(event);
+      if (streamError != null) {
+        throw streamError;
+      }
       const convertedChunk =
         convertResponsesDeltaToChatGenerationChunk(event) ??
         convertDroppedResponsesReplayOutput(event);

package/src/run.ts

@@ -26,6 +26,16 @@ import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
+import {
+  Callback,
+  GraphEvents,
+  TitleMethod,
+  ACTIVITY_LABEL_RUN_NAME,
+  REASONING_LABEL_RUN_NAME,
+  ACTIVITY_PHASE_RUN_NAME,
+  ACTIVITY_PHASE_LABEL_RUN_NAME,
+  DEFAULT_RECURSION_LIMIT,
+} from '@/common';
 import {
   requireValidSubagentResumeManifest,
   stripSubagentResumeManifest,
@@ -58,6 +68,10 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  resolveLangfuseDestinationKey,
+  resolveLangfuseTraceAnchorParent,
+} from '@/langfuseSpanRegistry';
 import {
   appendCallbacks,
   filterCallbacks,
@@ -72,17 +86,12 @@ import {
   getRunStepResumeState,
   stripRunStepResumeState,
 } from '@/tools/runStepResume';
-import {
-  Callback,
-  GraphEvents,
-  TitleMethod,
-  DEFAULT_RECURSION_LIMIT,
-} from '@/common';
 import {
   createCompletionTitleRunnable,
   createTitleRunnable,
 } from '@/utils/title';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
+import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { initializeLangfuseTracing } from './instrumentation';
 import { seedRunInitialSessions } from '@/utils/toolSessions';
@@ -986,6 +995,9 @@ export class Run<_T extends t.BaseGraphState> {
      * instead of `inputs.messages`.
      */
     const isResume = inputs instanceof Command;
+    if (!isResume) {
+      graph.startFreshLangfuseExecution();
+    }
     const stateInputs = isResume ? undefined : (inputs as t.IState);
     if (stateInputs != null) {
       this.activityPhaseTraceInput = findActivityPhaseTraceInput(
@@ -1116,6 +1128,7 @@ export class Run<_T extends t.BaseGraphState> {
         streamLangfuseConfig?.deterministicTraceId === true
           ? this.id
           : undefined,
+      traceAnchor: graph.langfuseTraceAnchor,
       // The graph's per-execution stamp, NOT the public run id: public ids
       // may repeat across concurrent executions (retries, tenant-local
       // message ids), and equal stamps defeat foreign-scope rejection.
@@ -1131,6 +1144,7 @@ export class Run<_T extends t.BaseGraphState> {
         streamLangfuseConfig?.deterministicTraceId === true
           ? this.id
           : undefined,
+      traceAnchor: graph.langfuseTraceAnchor,
       runId: graph.langfuseScopeRunId,
       // The aggregate multi-agent policy from the runtime scope — the
       // handler must restore THIS (not the primary agent's config-derived
@@ -1139,7 +1153,6 @@ export class Run<_T extends t.BaseGraphState> {
       traceName,
     });
     if (langfuseHandler != null) {
-      config.runName = traceName;
       config.callbacks = appendCallbacks(config.callbacks, [langfuseHandler]);
     }
 
@@ -1201,18 +1214,22 @@ export class Run<_T extends t.BaseGraphState> {
        * arg to `BaseGraphState`. Cast on the call so the resume path
        * type-checks without widening the wrapper for every caller.
        */
-      const stream = graphRunnable.streamEvents(inputs as t.IState, config, {
-        raiseError: true,
-        /**
-         * Prevent EventStreamCallbackHandler from processing custom events.
-         * Custom events are already handled via our createCustomEventCallback()
-         * which routes them through the handlerRegistry.
-         * Without this flag, EventStreamCallbackHandler throws errors when
-         * custom events are dispatched for run IDs not in its internal map
-         * (due to timing issues in parallel execution or after run cleanup).
-         */
-        ignoreCustomEvent: true,
-      });
+      const stream = graphRunnable.streamEvents(
+        inputs as t.IState,
+        { ...config, runName: graph.runName },
+        {
+          raiseError: true,
+          /**
+           * Prevent EventStreamCallbackHandler from processing custom events.
+           * Custom events are already handled via our createCustomEventCallback()
+           * which routes them through the handlerRegistry.
+           * Without this flag, EventStreamCallbackHandler throws errors when
+           * custom events are dispatched for run IDs not in its internal map
+           * (due to timing issues in parallel execution or after run cleanup).
+           */
+          ignoreCustomEvent: true,
+        }
+      );
 
       for await (const event of stream) {
         const { data, metadata, ...info } = event;
@@ -2123,6 +2140,7 @@ export class Run<_T extends t.BaseGraphState> {
     const labelAgentName =
       labelAgentId == null ? undefined : labelContext?.name;
     const labelMetadata: Record<string, unknown> = {
+      [LANGFUSE_OPERATION_METADATA_KEY]: ACTIVITY_LABEL_RUN_NAME,
       sourceRunId: this.id,
       responseId: this.id,
       activityIndex: labelIndex,
@@ -2132,7 +2150,7 @@ export class Run<_T extends t.BaseGraphState> {
       ...(labelAgentId == null ? {} : { agentId: labelAgentId }),
       ...(labelAgentName == null ? {} : { agentName: labelAgentName }),
     };
-    const traceMetadata = {
+    const traceMetadata: Record<string, string> = {
       ...createLangfuseTraceMetadata({
         messageId: 'activity-label-' + this.id,
         parentMessageId: labelParentMessageId,
@@ -2150,16 +2168,9 @@ export class Run<_T extends t.BaseGraphState> {
       labelContext?.langfuse
     );
     initializeLangfuseTracing(labelLangfuseConfig);
-    /** Seed policy, threading two constraints:
-     *  1. `runWithLangfuseRuntimeContext` SPREADS the surrounding context, so
-     *     an absent seed INHERITS the parent run's and collapses every label
-     *     into that trace. When a parent seed is active we must override it
-     *     with a per-label one.
-     *  2. Without deterministic tracing there is no parent seed, and forcing
-     *     one here would make label trace ids deterministic when neither
-     *     `processStream` nor `generateTitle` are — so leave it unset.
-     *  Seeded when determinism is opted into OR a parent seed is live;
-     *  otherwise unseeded, matching the other generation paths. */
+    /** A captured source observation parents the label in the agent trace.
+     *  The distinct seed remains the standalone fallback when labeling runs
+     *  before tracing starts or against another Langfuse destination. */
     const inheritedTraceSeed = getTraceIdSeed();
     const labelTraceSeed =
       labelLangfuseConfig?.deterministicTraceId === true ||
@@ -2174,6 +2185,15 @@ export class Run<_T extends t.BaseGraphState> {
       traceIdSeed: labelTraceSeed,
       runId: labelScopeRunId,
     });
+    const labelParentSpanContext = resolveLangfuseTraceAnchorParent(
+      this.Graph?.langfuseTraceAnchor,
+      resolveLangfuseDestinationKey(labelLangfuseConfig),
+      labelAgentId
+    );
+    if (labelParentSpanContext != null) {
+      labelMetadata.sourceTraceId = labelParentSpanContext.traceId;
+      traceMetadata.sourceTraceId = labelParentSpanContext.traceId;
+    }
     /** Handler only when a session id resolved from
      *  `chainOptions.configurable.thread_id`: without it the label call has
      *  no conversation identity, and tracing it would create an orphan
@@ -2187,15 +2207,18 @@ export class Run<_T extends t.BaseGraphState> {
         langfuse: labelLangfuseConfig,
         userId: labelUserId,
         sessionId: labelSessionId,
-        traceMetadata,
+        traceMetadata:
+          labelParentSpanContext == null ? traceMetadata : undefined,
         tags: labelTags,
         traceIdSeed:
           labelLangfuseConfig?.deterministicTraceId === true
             ? labelTraceSeed
             : undefined,
+        parentSpanContext: labelParentSpanContext,
+        inheritTraceIdentity: labelParentSpanContext != null,
         runId: labelScopeRunId,
         toolOutputTracing: labelRuntimeScope.toolOutputTracing,
-        traceName: labelRunName,
+        traceName: labelParentSpanContext == null ? labelRunName : undefined,
       });
     }
     if (labelLangfuseHandler != null) {
@@ -2297,9 +2320,11 @@ export class Run<_T extends t.BaseGraphState> {
           langfuse: labelLangfuseConfig,
           userId: labelUserId,
           sessionId: labelSessionId,
-          traceName: labelRunName,
-          traceMetadata,
+          traceName: labelParentSpanContext == null ? labelRunName : undefined,
+          traceMetadata:
+            labelParentSpanContext == null ? traceMetadata : undefined,
           tags: labelTags,
+          inheritTraceIdentity: labelParentSpanContext != null,
         },
         () =>
           model.invoke(
@@ -2457,6 +2482,7 @@ export class Run<_T extends t.BaseGraphState> {
     const resolvedSourceRunId = sourceRunId ?? this.id;
     const reasoningResponseId = responseId ?? this.id;
     const reasoningMetadata: Record<string, unknown> = {
+      [LANGFUSE_OPERATION_METADATA_KEY]: REASONING_LABEL_RUN_NAME,
       sourceRunId: resolvedSourceRunId,
       ...(sourceTraceId == null ? {} : { sourceTraceId }),
       responseId: reasoningResponseId,
@@ -2470,7 +2496,7 @@ export class Run<_T extends t.BaseGraphState> {
       ...(reasoningAgentId == null ? {} : { agentId: reasoningAgentId }),
       ...(reasoningAgentName == null ? {} : { agentName: reasoningAgentName }),
     };
-    const traceMetadata = {
+    const traceMetadata: Record<string, string> = {
       ...createLangfuseTraceMetadata({
         messageId: `reasoning-label-${reasoningResponseId}`,
         parentMessageId: reasoningParentMessageId,
@@ -2512,21 +2538,40 @@ export class Run<_T extends t.BaseGraphState> {
       traceIdSeed: reasoningTraceSeed,
       runId: reasoningScopeRunId,
     });
+    const candidateReasoningParent = resolveLangfuseTraceAnchorParent(
+      this.Graph?.langfuseTraceAnchor,
+      resolveLangfuseDestinationKey(reasoningLangfuseConfig),
+      reasoningAgentId
+    );
+    const reasoningParentSpanContext =
+      resolvedSourceRunId === this.id &&
+      (sourceTraceId == null ||
+        sourceTraceId === candidateReasoningParent?.traceId)
+        ? candidateReasoningParent
+        : undefined;
+    if (reasoningParentSpanContext != null) {
+      reasoningMetadata.sourceTraceId = reasoningParentSpanContext.traceId;
+      traceMetadata.sourceTraceId = reasoningParentSpanContext.traceId;
+    }
     let reasoningLangfuseHandler: CallbackEntry | undefined;
     if (reasoningSessionId != null) {
       reasoningLangfuseHandler = createLangfuseHandler({
         langfuse: reasoningLangfuseConfig,
         userId: reasoningUserId,
         sessionId: reasoningSessionId,
-        traceMetadata,
+        traceMetadata:
+          reasoningParentSpanContext == null ? traceMetadata : undefined,
         tags: reasoningTags,
         traceIdSeed:
           reasoningLangfuseConfig?.deterministicTraceId === true
             ? reasoningTraceSeed
             : undefined,
+        parentSpanContext: reasoningParentSpanContext,
+        inheritTraceIdentity: reasoningParentSpanContext != null,
         runId: reasoningScopeRunId,
         toolOutputTracing: reasoningRuntimeScope.toolOutputTracing,
-        traceName: reasoningRunName,
+        traceName:
+          reasoningParentSpanContext == null ? reasoningRunName : undefined,
       });
     }
     if (reasoningLangfuseHandler != null) {
@@ -2585,9 +2630,12 @@ export class Run<_T extends t.BaseGraphState> {
           langfuse: reasoningLangfuseConfig,
           userId: reasoningUserId,
           sessionId: reasoningSessionId,
-          traceName: reasoningRunName,
-          traceMetadata,
+          traceName:
+            reasoningParentSpanContext == null ? reasoningRunName : undefined,
+          traceMetadata:
+            reasoningParentSpanContext == null ? traceMetadata : undefined,
           tags: reasoningTags,
+          inheritTraceIdentity: reasoningParentSpanContext != null,
         },
         () =>
           model.invoke(
@@ -2638,9 +2686,10 @@ export class Run<_T extends t.BaseGraphState> {
 
   /**
    * Generates one parent summary for two or more logical activities. The
-   * summary model is traced as a dedicated activity-phase chain root in the
-   * conversation session, with the model callback recorded as its generation
-   * child. No session id means no phase trace, avoiding orphan observations.
+   * summary model is traced as an activity-phase chain beneath the source
+   * agent run, with the model callback recorded as its generation child. It
+   * falls back to a dedicated trace when no source observation is available.
+   * No session id means no phase trace, avoiding orphan observations.
    */
   async generateActivityPhaseLabel({
     provider,
@@ -2771,6 +2820,7 @@ export class Run<_T extends t.BaseGraphState> {
     const phaseParentMessageId =
       phaseChainOptions.configurable?.requestBody?.parentMessageId;
     const phaseMetadata: Record<string, unknown> = {
+      [LANGFUSE_OPERATION_METADATA_KEY]: ACTIVITY_PHASE_LABEL_RUN_NAME,
       sourceRunId: sourceRunId ?? this.id,
       ...(sourceTraceId == null ? {} : { sourceTraceId }),
       responseId: phaseMessageId,
@@ -2785,7 +2835,7 @@ export class Run<_T extends t.BaseGraphState> {
       ...(phaseAgentName == null ? {} : { agentName: phaseAgentName }),
       ...(closingTextPhase == null ? {} : { closingTextPhase }),
     };
-    const traceMetadata = {
+    const traceMetadata: Record<string, string> = {
       ...createLangfuseTraceMetadata({
         messageId: phaseMessageId,
         parentMessageId: phaseParentMessageId,
@@ -2826,6 +2876,19 @@ export class Run<_T extends t.BaseGraphState> {
       traceIdSeed: phaseTraceSeed,
       runId: phaseScopeRunId,
     });
+    const candidatePhaseParent = resolveLangfuseTraceAnchorParent(
+      this.Graph?.langfuseTraceAnchor,
+      resolveLangfuseDestinationKey(phaseLangfuseConfig)
+    );
+    const phaseParentSpanContext =
+      (sourceRunId == null || sourceRunId === this.id) &&
+      (sourceTraceId == null || sourceTraceId === candidatePhaseParent?.traceId)
+        ? candidatePhaseParent
+        : undefined;
+    if (phaseParentSpanContext != null) {
+      phaseMetadata.sourceTraceId = phaseParentSpanContext.traceId;
+      traceMetadata.sourceTraceId = phaseParentSpanContext.traceId;
+    }
     let phaseLangfuseHandler: CallbackEntry | undefined;
     const sourceUserText =
       this.activityPhaseTraceInput ??
@@ -2835,15 +2898,18 @@ export class Run<_T extends t.BaseGraphState> {
         langfuse: phaseLangfuseConfig,
         userId: phaseUserId,
         sessionId: phaseSessionId,
-        traceMetadata,
+        traceMetadata:
+          phaseParentSpanContext == null ? traceMetadata : undefined,
         tags: phaseTags,
         traceIdSeed:
           phaseLangfuseConfig?.deterministicTraceId === true
             ? phaseTraceSeed
             : undefined,
+        parentSpanContext: phaseParentSpanContext,
+        inheritTraceIdentity: phaseParentSpanContext != null,
         runId: phaseScopeRunId,
         toolOutputTracing: phaseRuntimeScope.toolOutputTracing,
-        traceName: phaseTraceName,
+        traceName: phaseParentSpanContext == null ? phaseTraceName : undefined,
       });
     }
     if (phaseLangfuseHandler != null) {
@@ -2864,7 +2930,7 @@ export class Run<_T extends t.BaseGraphState> {
     const invokeConfig = Object.assign({}, phaseChainOptions, {
       run_id: phaseRunId,
       runId: phaseRunId,
-      runName: 'summarize-activity-phase',
+      runName: ACTIVITY_PHASE_RUN_NAME,
       tags: [...new Set([...(phaseChainOptions.tags ?? []), ...phaseTags])],
       metadata: {
         ...(phaseChainOptions.metadata ?? {}),
@@ -2943,7 +3009,7 @@ export class Run<_T extends t.BaseGraphState> {
           ? { label, messages: [new AIMessage(label)] }
           : { messages: [] };
       },
-    }).withConfig({ runName: 'summarize-activity-phase' });
+    }).withConfig({ runName: ACTIVITY_PHASE_RUN_NAME });
 
     try {
       const result = await withLangfuseRuntimeScope(phaseRuntimeScope, () =>
@@ -2952,9 +3018,12 @@ export class Run<_T extends t.BaseGraphState> {
             langfuse: phaseLangfuseConfig,
             userId: phaseUserId,
             sessionId: phaseSessionId,
-            traceName: phaseTraceName,
-            traceMetadata,
+            traceName:
+              phaseParentSpanContext == null ? phaseTraceName : undefined,
+            traceMetadata:
+              phaseParentSpanContext == null ? traceMetadata : undefined,
             tags: phaseTags,
+            inheritTraceIdentity: phaseParentSpanContext != null,
           },
           () =>
             phaseRunnable.invoke(