fix(core): preserve tracingOptions.tags when merging defaultOptions (#12220)

Tags set in `defaultOptions.tracingOptions.tags` were being lost when
merging with call-site options due to shallow spreading. Now using
`deepMerge` to properly preserve nested properties.

**Before (broken):**
```typescript
const agent = new Agent({
  defaultOptions: {
    tracingOptions: { tags: ['default-tag'] }
  }
});

// Passing any tracingOptions property would lose the default tags
await agent.generate(messages, {
  tracingOptions: { metadata: { userId: '123' } }
});
// tags: undefined ❌
```

**After (fixed):**
```typescript
// Same setup - tags are now preserved
await agent.generate(messages, {
  tracingOptions: { metadata: { userId: '123' } }
});
// tags: ['default-tag'] ✓
```

This fix works for all observability exporters (Langfuse, Langsmith,
Braintrust, Datadog, Sentry, Laminar, PostHog) since it's in the core
agent code.

NOTE: tested with langfuse cloud and brainstrust cloud

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: roaminro

.changeset/green-singers-share.md

@@ -0,0 +1,6 @@
+---
+'@mastra/observability': patch
+'@mastra/core': patch
+---
+
+Fixed tracingOptions.tags not being preserved when merging defaultOptions with call-site options. Tags set in agent's defaultOptions.tracingOptions are now correctly passed to all observability exporters (Langfuse, Langsmith, Braintrust, Datadog, etc.). Fixes #12209.

observability/mastra/src/integration-tests.test.ts

@@ -2241,4 +2241,220 @@ describe('Tracing Integration Tests', () => {
       });
     },
   );
+
+  /**
+   * Tests that tags set in tracingOptions (either via defaultOptions or in generate/stream call)
+   * are properly passed through to the exported spans and received by exporters.
+   */
+  describe('tracingOptions.tags support (Issue #12209)', () => {
+    it('should pass tags from defaultOptions.tracingOptions to exported spans', async () => {
+      const testAgent = new Agent({
+        id: 'test-agent-with-tags',
+        name: 'Test Agent With Tags',
+        instructions: 'You are a test agent',
+        model: mockModelV2,
+        defaultOptions: {
+          tracingOptions: {
+            tags: ['production', 'test-tag', 'experiment-v1'],
+          },
+        },
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        agents: { testAgent },
+      });
+
+      const agent = mastra.getAgent('testAgent');
+      // Call generate WITHOUT passing tracingOptions - should use defaultOptions
+      const result = await agent.generate('Hello');
+
+      expect(result.text).toBeDefined();
+      expect(result.traceId).toBeDefined();
+
+      const agentRunSpans = testExporter.getSpansByType(SpanType.AGENT_RUN);
+      expect(agentRunSpans.length).toBe(1);
+
+      const agentRunSpan = agentRunSpans[0];
+      expect(agentRunSpan?.isRootSpan).toBe(true);
+      expect(agentRunSpan?.traceId).toBe(result.traceId);
+
+      // CRITICAL: Tags from defaultOptions.tracingOptions should appear on the root span
+      expect(agentRunSpan?.tags).toBeDefined();
+      expect(agentRunSpan?.tags).toEqual(['production', 'test-tag', 'experiment-v1']);
+
+      testExporter.finalExpectations();
+    });
+
+    it('should pass tags from generate call tracingOptions to exported spans', async () => {
+      const testAgent = new Agent({
+        id: 'test-agent-tags-call',
+        name: 'Test Agent Tags Call',
+        instructions: 'You are a test agent',
+        model: mockModelV2,
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        agents: { testAgent },
+      });
+
+      const agent = mastra.getAgent('testAgent');
+      // Call generate WITH explicit tracingOptions.tags
+      const result = await agent.generate('Hello', {
+        tracingOptions: {
+          tags: ['call-tag-1', 'call-tag-2'],
+        },
+      });
+
+      expect(result.text).toBeDefined();
+      expect(result.traceId).toBeDefined();
+
+      const agentRunSpans = testExporter.getSpansByType(SpanType.AGENT_RUN);
+      expect(agentRunSpans.length).toBe(1);
+
+      const agentRunSpan = agentRunSpans[0];
+      expect(agentRunSpan?.isRootSpan).toBe(true);
+      expect(agentRunSpan?.traceId).toBe(result.traceId);
+
+      // Tags from the generate call should appear on the root span
+      expect(agentRunSpan?.tags).toBeDefined();
+      expect(agentRunSpan?.tags).toEqual(['call-tag-1', 'call-tag-2']);
+
+      testExporter.finalExpectations();
+    });
+
+    it('should merge tags from defaultOptions and generate call tracingOptions', async () => {
+      const testAgent = new Agent({
+        id: 'test-agent-merge-tags',
+        name: 'Test Agent Merge Tags',
+        instructions: 'You are a test agent',
+        model: mockModelV2,
+        defaultOptions: {
+          tracingOptions: {
+            tags: ['default-tag'],
+            metadata: { source: 'default' },
+          },
+        },
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        agents: { testAgent },
+      });
+
+      const agent = mastra.getAgent('testAgent');
+      // Call generate with additional tracingOptions - tags should be merged or call-site should win
+      // The current behavior (shallow merge) will lose the default tags entirely
+      // This test documents the expected behavior: call-site tags override defaults
+      const result = await agent.generate('Hello', {
+        tracingOptions: {
+          tags: ['call-tag'],
+          metadata: { source: 'call' },
+        },
+      });
+
+      expect(result.text).toBeDefined();
+      expect(result.traceId).toBeDefined();
+
+      const agentRunSpans = testExporter.getSpansByType(SpanType.AGENT_RUN);
+      expect(agentRunSpans.length).toBe(1);
+
+      const agentRunSpan = agentRunSpans[0];
+
+      // With shallow merge, call-site tracingOptions completely replaces defaultOptions.tracingOptions
+      // So we expect only the call-site tags to be present
+      expect(agentRunSpan?.tags).toBeDefined();
+      expect(agentRunSpan?.tags).toEqual(['call-tag']);
+
+      testExporter.finalExpectations();
+    });
+
+    it('should preserve defaultOptions.tracingOptions.tags when call passes other tracingOptions properties', async () => {
+      const testAgent = new Agent({
+        id: 'test-agent-preserve-tags',
+        name: 'Test Agent Preserve Tags',
+        instructions: 'You are a test agent',
+        model: mockModelV2,
+        defaultOptions: {
+          tracingOptions: {
+            tags: ['preserve-this-tag'],
+          },
+        },
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        agents: { testAgent },
+      });
+
+      const agent = mastra.getAgent('testAgent');
+      // Call generate with tracingOptions that has metadata but NO tags
+      // BUG: The shallow merge will replace the entire tracingOptions object,
+      // causing the tags from defaultOptions to be lost
+      const result = await agent.generate('Hello', {
+        tracingOptions: {
+          metadata: { someKey: 'someValue' },
+        },
+      });
+
+      expect(result.text).toBeDefined();
+      expect(result.traceId).toBeDefined();
+
+      const agentRunSpans = testExporter.getSpansByType(SpanType.AGENT_RUN);
+      expect(agentRunSpans.length).toBe(1);
+
+      const agentRunSpan = agentRunSpans[0];
+
+      // EXPECTED: Tags from defaultOptions should be preserved when call doesn't specify tags
+      // ACTUAL BUG: Tags are undefined because shallow merge replaces entire tracingOptions
+      expect(agentRunSpan?.tags).toBeDefined();
+      expect(agentRunSpan?.tags).toEqual(['preserve-this-tag']);
+
+      testExporter.finalExpectations();
+    });
+
+    it('should pass tags from stream call tracingOptions to exported spans', async () => {
+      const testAgent = new Agent({
+        id: 'test-agent-stream-tags',
+        name: 'Test Agent Stream Tags',
+        instructions: 'You are a test agent',
+        model: mockModelV2,
+        defaultOptions: {
+          tracingOptions: {
+            tags: ['stream-default-tag'],
+          },
+        },
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        agents: { testAgent },
+      });
+
+      const agent = mastra.getAgent('testAgent');
+      // Call stream without passing any options - should use defaultOptions
+      const result = await agent.stream('Hello');
+      // Consume stream to complete
+      let fullText = '';
+      for await (const chunk of result.textStream) {
+        fullText += chunk;
+      }
+
+      expect(fullText).toBeDefined();
+      expect(result.traceId).toBeDefined();
+
+      const agentRunSpans = testExporter.getSpansByType(SpanType.AGENT_RUN);
+      expect(agentRunSpans.length).toBe(1);
+
+      const agentRunSpan = agentRunSpans[0];
+      expect(agentRunSpan?.isRootSpan).toBe(true);
+
+      // Tags from defaultOptions.tracingOptions should appear on the root span
+      expect(agentRunSpan?.tags).toBeDefined();
+      expect(agentRunSpan?.tags).toEqual(['stream-default-tag']);
+
+      testExporter.finalExpectations();
+    });
+  });
 });

packages/core/src/agent/agent.ts

@@ -43,7 +43,7 @@ import type { FullOutput, MastraModelOutput } from '../stream/base/output';
 import { createTool } from '../tools';
 import type { CoreTool } from '../tools/types';
 import type { DynamicArgument } from '../types';
-import { makeCoreTool, createMastraProxy, ensureToolProperties, isZodType } from '../utils';
+import { makeCoreTool, createMastraProxy, ensureToolProperties, isZodType, deepMerge } from '../utils';
 import type { ToolOptions } from '../utils';
 import type { MastraVoice } from '../voice';
 import { DefaultVoice } from '../voice';
@@ -3322,10 +3322,10 @@ export class Agent<
     const defaultOptions = await this.getDefaultOptions({
       requestContext: options?.requestContext,
     });
-    const mergedOptions = {
-      ...defaultOptions,
-      ...(options ?? {}),
-    } as unknown as AgentExecutionOptions<any>;
+    const mergedOptions = deepMerge(
+      defaultOptions as Record<string, unknown>,
+      (options ?? {}) as Record<string, unknown>,
+    ) as AgentExecutionOptions<any>;
 
     const llm = await this.getLLM({
       requestContext: mergedOptions.requestContext,
@@ -3412,10 +3412,10 @@ export class Agent<
     const defaultOptions = await this.getDefaultOptions({
       requestContext: streamOptions?.requestContext,
     });
-    const mergedOptions = {
-      ...defaultOptions,
-      ...(streamOptions ?? {}),
-    } as unknown as AgentExecutionOptions<OUTPUT>;
+    const mergedOptions = deepMerge(
+      defaultOptions as Record<string, unknown>,
+      (streamOptions ?? {}) as Record<string, unknown>,
+    ) as AgentExecutionOptions<OUTPUT>;
 
     const llm = await this.getLLM({
       requestContext: mergedOptions.requestContext,
@@ -3513,10 +3513,10 @@ export class Agent<
       requestContext: streamOptions?.requestContext,
     });
 
-    let mergedStreamOptions = {
-      ...defaultOptions,
-      ...streamOptions,
-    };
+    let mergedStreamOptions = deepMerge(
+      defaultOptions as Record<string, unknown>,
+      (streamOptions ?? {}) as Record<string, unknown>,
+    ) as typeof defaultOptions;
 
     const llm = await this.getLLM({
       requestContext: mergedStreamOptions.requestContext,
@@ -3591,10 +3591,10 @@ export class Agent<
       requestContext: options?.requestContext,
     });
 
-    const mergedOptions = {
-      ...defaultOptions,
-      ...(options ?? {}),
-    };
+    const mergedOptions = deepMerge(
+      defaultOptions as Record<string, unknown>,
+      (options ?? {}) as Record<string, unknown>,
+    ) as typeof defaultOptions;
 
     const llm = await this.getLLM({
       requestContext: mergedOptions.requestContext,

packages/core/src/utils.ts

@@ -24,28 +24,33 @@ export { getZodTypeName, getZodDef, isZodArray, isZodObject } from './utils/zod-
 export const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
 /**
- * Deep merges two objects, recursively merging nested objects and arrays
+ * Checks if a value is a plain object (not an array, function, Date, RegExp, etc.)
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep merges two objects, recursively merging nested plain objects.
+ * Arrays, functions, and other non-plain objects are replaced (not merged).
  */
 export function deepMerge<T extends object = object>(target: T, source: Partial<T>): T {
   const output = { ...target };
 
   if (!source) return output;
 
   Object.keys(source).forEach(key => {
-    const targetValue = output[key as keyof T];
-    const sourceValue = source[key as keyof T];
-
-    if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
-      (output as any)[key] = sourceValue;
-    } else if (
-      sourceValue instanceof Object &&
-      targetValue instanceof Object &&
-      !Array.isArray(sourceValue) &&
-      !Array.isArray(targetValue)
-    ) {
-      (output as any)[key] = deepMerge(targetValue, sourceValue as T);
+    const targetValue = (output as Record<string, unknown>)[key];
+    const sourceValue = (source as Record<string, unknown>)[key];
+
+    // Only deep merge if both values are plain objects
+    if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+      (output as Record<string, unknown>)[key] = deepMerge(targetValue, sourceValue);
     } else if (sourceValue !== undefined) {
-      (output as any)[key] = sourceValue;
+      // For arrays, functions, primitives, and other non-plain objects: replace
+      (output as Record<string, unknown>)[key] = sourceValue;
     }
   });