github mastra-ai/mastra @mastra/core@1.24.0
April 7, 20206
on GitHub

10 hours ago

Highlights

End-to-end RAG Tracing + New RAG/Graph Span Types

RAG ingestion and query operations are now visible in Mastra tracing with new span types (e.g., RAG_INGESTION, RAG_EMBEDDING, RAG_VECTOR_OPERATION, RAG_ACTION, GRAPH_ACTION) plus helpers like startRagIngestion() / withRagIngestion(). Instrumentation is opt-in via an observabilityContext, and @mastra/rag automatically threads context from agent TOOL_CALL spans into vector and graph tools.

CloudExporter Now Ships All Observability Signals (Not Just Traces)

@mastra/observability CloudExporter can now batch and upload logs, metrics, scores, and feedback in addition to tracing spans, enabling a single exporter path to Mastra Cloud for all signals. This also changes the endpoint configuration to use a base collector URL and derive publish paths automatically.

Span Filtering to Reduce Observability Noise and Cost

excludeSpanTypes and spanFilter were added to ObservabilityInstanceConfig in both @mastra/core and @mastra/observability, allowing you to drop entire span categories (e.g., MODEL_CHUNK) or apply predicate-based filtering before export—useful for pay-per-span backends.

AI SDK v6 Message Support + Message Interop Helpers

@mastra/core MessageList can now accept AI SDK v6 UI/model messages and project stored messages via messageList.get.all.aiV6.ui(), supporting v6 approval request/response flows. @mastra/ai-sdk adds toAISdkMessages() to load stored Mastra messages into AI SDK v5 or v6 chat UIs.

Better Reliability and Debuggability Across Logs + MCP + Memory

Observability log correlation is fixed so logs inside agent runs carry the active span correlation fields (restoring trace↔log linking), and deepClean() now applies to all signals and better preserves Map/Set/Error detail. MCP tool discovery now retries after reconnectable errors and the MCP server returns spec-correct 404s for stale sessions; memory recall gains more precise browsing (partType, toolName, threadId: "current", anchor paging), and message parts now include createdAt timestamps for accurate part-level timing.

Breaking Changes

  • CloudExporter endpoint format changed: configure a base endpoint URL (publisher paths are derived automatically) when using CloudExporter for Mastra Cloud uploads.

Changelog

@mastra/core@1.24.0

Minor Changes

  • Added excludeSpanTypes and spanFilter options to ObservabilityInstanceConfig for selectively filtering spans before export. Use excludeSpanTypes to drop entire categories of spans by type (e.g., MODEL_CHUNK, MODEL_STEP) or spanFilter for fine-grained predicate-based filtering by attributes, metadata, entity, or any combination. Both options help reduce noise and costs in observability platforms that charge per-span. (#15131)

    excludeSpanTypes example: 

    excludeSpanTypes: [SpanType.MODEL_CHUNK, SpanType.MODEL_STEP, SpanType.WORKFLOW_SLEEP];

    spanFilter example: 

    spanFilter: span => {
  if (span.type === SpanType.MODEL_CHUNK) return false;
  if (span.type === SpanType.TOOL_CALL && span.attributes?.success) return false;
  return true;
};

    Resolves #12710

  • Add RAG observability (#10898) (#15137)

    Surfaces RAG ingestion and query operations in Mastra's AI tracing.

    New span types in @mastra/core/observability:

    • RAG_INGESTION (root) — wraps an ingestion pipeline run
    • RAG_EMBEDDING — embedding call (used by ingestion and query)
    • RAG_VECTOR_OPERATION — vector store I/O (query/upsert/delete/fetch)
    • RAG_ACTION — chunk / extract_metadata / rerank
    • GRAPH_ACTION — non-RAG graph build / traverse / update / prune

    New helpers exported from @mastra/core/observability:

    • startRagIngestion(opts) — manual: returns { span, observabilityContext }
    • withRagIngestion(opts, fn) — scoped: runs fn(observabilityContext),
      attaches the return value as the span's output, routes thrown errors to
      span.error(...)

    Wired in @mastra/rag:

    • vectorQuerySearch emits RAG_EMBEDDING (mode: query) and
      RAG_VECTOR_OPERATION (operation: query)
    • rerank / rerankWithScorer emit RAG_ACTION (action: rerank)
    • MDocument.chunk emits RAG_ACTION (action: chunk) and
      RAG_ACTION (action: extract_metadata)
    • createGraphRAGTool emits GRAPH_ACTION (action: build / traverse)
    • createVectorQueryTool and createGraphRAGTool thread
      observabilityContext from the agent's TOOL_CALL span automatically

    All new instrumentation is opt-in: functions accept an optional
    observabilityContext and no-op when absent, so existing callers are
    unaffected.

Patch Changes

  • Update provider registry and model documentation with latest models and providers (8db7663)

  • Added AI SDK v6 UI message support to MessageList in @mastra/core. (#14592)

    MessageList can now accept AI SDK v6 UI and model messages in add(...), and project stored messages with messageList.get.all.aiV6.ui(). This adds first-class handling for v6 approval request and response message flows.

  • Fix observability log correlation: logs emitted from inside an agent run were being persisted with entityId, runId, traceId, and the other correlation fields set to null, breaking trace ↔ log linking in Mastra Studio and downstream observability tools. Logs now correctly carry the active span's correlation context end to end. (#15148)

  • Added createdAt timestamps to message parts in message history. (#15121)

    Message parts now keep their own creation timestamps so downstream code can preserve part-level timing instead of relying only on the parent message timestamp.

    After: 

    { type: 'text', text: 'hello', createdAt: 1712534400000 }

@mastra/ai-sdk@1.3.3

Patch Changes

  • Added toAISdkMessages() for loading stored Mastra messages into AI SDK v5 or v6 chat UIs. (#14592)

    Use the default v5 behavior or pass { version: 'v6' } when your app is typed against AI SDK v6 useChat() message types.

@mastra/client-js@1.13.2

Patch Changes

  • Fixed the client JS Responses types to allow omitting the model override. (#15140)

@mastra/datadog@1.0.15

Patch Changes

  • Fix Datadog LLM Observability span kinds for model spans so traces match Datadog's expected shape. (#15149)
    • Each call to a model now shows up as an llm span in Datadog (previously the per-call spans were reported as task, so Datadog's "Model Calls" count was wrong and per-call inputs/outputs were not rendered as messages).
    • The wrapper around a generation is now reported as a workflow span instead of llm, so it no longer looks like an extra LLM call.
    • Token usage and cost are reported only on the per-call llm spans, so Datadog no longer double-counts tokens against the wrapper.
    • Per-call llm spans inherit modelName and modelProvider from their parent generation, so the model is still attached in the Datadog UI.

@mastra/loggers@1.1.1

Patch Changes

  • Removed 'component' field from pino-pretty log output to reduce noise in CLI logs (#15146)

@mastra/mcp@1.4.2

Patch Changes

  • Improved MCP tool discovery to retry once after reconnectable connection errors like Connection closed during tools/list. (#15141)

    MCPClient.listToolsets(), listToolsetsWithErrors(), and listTools() now attempt a reconnect before treating transient discovery failures as missing tools.

  • Fixed MCP server to return HTTP 404 (instead of 400) when a client sends a stale or unknown session ID. Per the MCP spec, this tells clients to re-initialize with a new session, which fixes broken tool calls after server redeploys. (#15160)

@mastra/memory@1.15.0

Minor Changes

  • Updated the recall tool to support more precise message browsing for agents. (#15116)

    Agents using recall can now pass partType and toolName to narrow message results to specific parts, such as tool calls or tool results for one tool. This change also adds threadId: "current" support across recall modes and anchor: "start" | "end" for no-cursor message paging, making it easier to inspect recent thread activity and past tool usage.

Patch Changes

  • Fixed reflection threshold not respecting per-record overrides set via the PATCH API. Previously, lowering the reflection threshold for a specific record had no effect on the actual reflection trigger — only the default 40k threshold was used. Now per-record overrides are correctly applied in both sync and async reflection paths. (#15170)

  • Improved observational memory formatting to use part timestamps when rendering dates and times. (#15121)

    Observer history now follows part-level timing more closely, so the rendered memory context is more accurate when messages contain parts created at different times.

  • Fixed message history doubling when using Observational Memory with the Mastra gateway. The local ObservationalMemoryProcessor now detects when the agent's model is routed through the Mastra gateway and skips its input/output processing, since the gateway handles OM server-side. (#15161)

@mastra/observability@1.8.0

Minor Changes

  • Added CloudExporter support for Mastra Observability logs, metrics, scores, and feedback. (#15124)

    CloudExporter now batches and uploads all Mastra Observability signals to Mastra Cloud, not just tracing spans.

    This includes a breaking change to the CloudExporter endpoint format. We now pass a base endpoint URL and let let the exporter derive the standard publish paths automatically. 

    import { CloudExporter, Observability } from '@mastra/observability';

const observability = new Observability({
  configs: {
    default: {
      serviceName: 'my-app',
      exporters: [
        new CloudExporter({
          endpoint: 'https://collector.example.com',
        }),
      ],
    },
  },
});

// Traces, logs, metrics, scores, and feedback now all publish through CloudExporter.

    After updating the exporter endpoint config, the exporter will continue to work for traces, and the same exporter will now also publish structured logs, auto-extracted metrics, scores, and feedback records.

  • Added excludeSpanTypes and spanFilter options to ObservabilityInstanceConfig for selectively filtering spans before export. Use excludeSpanTypes to drop entire categories of spans by type (e.g., MODEL_CHUNK, MODEL_STEP) or spanFilter for fine-grained predicate-based filtering by attributes, metadata, entity, or any combination. Both options help reduce noise and costs in observability platforms that charge per-span. (#15131)

    excludeSpanTypes example: 

    excludeSpanTypes: [SpanType.MODEL_CHUNK, SpanType.MODEL_STEP, SpanType.WORKFLOW_SLEEP];

    spanFilter example: 

    spanFilter: span => {
  if (span.type === SpanType.MODEL_CHUNK) return false;
  if (span.type === SpanType.TOOL_CALL && span.attributes?.success) return false;
  return true;
};

    Resolves #12710

Patch Changes

  • ObservabilityBus now honors per-instance serializationOptions (maxStringLength, maxDepth, maxArrayLength, maxObjectKeys) when deep-cleaning log/metric/score/feedback payloads, matching the behavior of tracing spans. Previously these signals always used the built-in defaults regardless of user configuration. (#15138)

  • Apply deepClean() to all observability signals (logs, metrics, scores, feedback) before fanning out to exporters and bridges. Previously only tracing spans were deep-cleaned at construction time, leaving free-form payload fields on other signals (e.g. log.data, log.metadata, metric.metadata, metric.costContext.costMetadata, score.metadata, feedback.metadata) susceptible to circular references, oversized strings, and other non-serializable values. Sanitization now happens centrally in ObservabilityBus.emit() so every signal leaving the bus is bounded and JSON-safe. (#15135)

  • deepClean() now preserves data for Map, Set, and richer Error objects. Previously Maps and Sets were serialized as empty {} (entries silently dropped) and Errors only kept name/message. Maps are now converted to plain objects of entries, Sets to arrays (both respecting maxObjectKeys/maxArrayLength and cycle detection), and Errors additionally preserve stack and recursively cleaned cause. (#15136)

@mastra/playground-ui@22.1.0

Minor Changes

  • Search input can now be collapsed into a compact icon button with tooltip and auto-focuses when expanded (#15130)

  • Added DataKeysAndValues component — a compound component for displaying key-value pairs in a grid layout with support for single or two-column modes and section headers (#15126)

  • Added DateTimeRangePicker component — a date range selector with preset options (last 24h, 7d, 30d, etc.) and a custom range mode with dual calendar and time pickers (#15128)

  • Added DataCodeSection component — a read-only code viewer with JSON syntax highlighting, search, multiline toggle, and an expandable fullscreen dialog (#15125)

  • Added DataPanel compound component — a container for detail panels with header, navigation, close button, loading, and empty states (#15127)

  • New inline Traces page replacing the old dialog-based Observability page. Trace, span, and score details now open in stacked side panels instead of full-screen dialogs. URL deep-linking supports traceId, spanId, tab, and scoreId params. Includes new TracesDataList, DataList.Pagination, DataList.Subheader components, and Evaluate Trace / Save as Dataset Item actions. (#15139)

Patch Changes

  • Fixed publishing older agent versions (#15154)

    Fixed agent editor to allow publishing older read-only versions. Previously, the Publish button was disabled when viewing a previous version. Now a "Publish This Version" button appears, enabling users to set any older version as the published version.

    Fixed Publish button being clickable without a saved draft

    The Publish button is now disabled until a draft version is saved. Previously, making edits would enable the Publish button even without a saved draft, which caused an error when clicked.

    Eliminated spurious 404 error logs for code-only agents

    The agent versions endpoint now checks both code-registered and stored agents before returning 404, and the frontend conditionally fetches stored agent details only when versions exist. This prevents noisy error logs when navigating to the editor for agents that haven't been published yet.

    Changed editor sections to be collapsed by default

    The System Prompt, Tools, and Variables sections in the agent editor are now collapsed by default when navigating to the editor page.

@mastra/rag@2.2.0

Minor Changes

  • Add RAG observability (#10898) (#15137)

    Surfaces RAG ingestion and query operations in Mastra's AI tracing.

    New span types in @mastra/core/observability:

    • RAG_INGESTION (root) — wraps an ingestion pipeline run
    • RAG_EMBEDDING — embedding call (used by ingestion and query)
    • RAG_VECTOR_OPERATION — vector store I/O (query/upsert/delete/fetch)
    • RAG_ACTION — chunk / extract_metadata / rerank
    • GRAPH_ACTION — non-RAG graph build / traverse / update / prune

    New helpers exported from @mastra/core/observability:

    • startRagIngestion(opts) — manual: returns { span, observabilityContext }
    • withRagIngestion(opts, fn) — scoped: runs fn(observabilityContext),
      attaches the return value as the span's output, routes thrown errors to
      span.error(...)

    Wired in @mastra/rag:

    • vectorQuerySearch emits RAG_EMBEDDING (mode: query) and
      RAG_VECTOR_OPERATION (operation: query)
    • rerank / rerankWithScorer emit RAG_ACTION (action: rerank)
    • MDocument.chunk emits RAG_ACTION (action: chunk) and
      RAG_ACTION (action: extract_metadata)
    • createGraphRAGTool emits GRAPH_ACTION (action: build / traverse)
    • createVectorQueryTool and createGraphRAGTool thread
      observabilityContext from the agent's TOOL_CALL span automatically

    All new instrumentation is opt-in: functions accept an optional
    observabilityContext and no-op when absent, so existing callers are
    unaffected.

Patch Changes

@mastra/server@1.24.0

Patch Changes

  • Fixed publishing older agent versions (#15154)

    Fixed agent editor to allow publishing older read-only versions. Previously, the Publish button was disabled when viewing a previous version. Now a "Publish This Version" button appears, enabling users to set any older version as the published version.

    Fixed Publish button being clickable without a saved draft

    The Publish button is now disabled until a draft version is saved. Previously, making edits would enable the Publish button even without a saved draft, which caused an error when clicked.

    Eliminated spurious 404 error logs for code-only agents

    The agent versions endpoint now checks both code-registered and stored agents before returning 404, and the frontend conditionally fetches stored agent details only when versions exist. This prevents noisy error logs when navigating to the editor for agents that haven't been published yet.

    Changed editor sections to be collapsed by default

    The System Prompt, Tools, and Variables sections in the agent editor are now collapsed by default when navigating to the editor page.

  • Fixed the Responses API to use the agent default model when create requests omit model. (#15140)

Other updated packages

The following packages were updated with dependency changes only:

Check out latest releases or
releases around mastra-ai/mastra @mastra/core@1.24.0

Don't miss a new mastra release

NewReleases is sending notifications on new releases.

Get notifications