2025-05-21 - Mastra Release

This release introduces several breaking changes. For more information on breaking changes please refer to this blog post

Workflows

• Type corrections for the getInitData function to improve type safety and accuracy. #4323
• New type for vNext workflow run. #4236
  -Fix type issues in inngest workflows. #4249
• Fix workflow run process to improve its structure and clarity. #4335
• A description field to the vnext workflow response. #4337
• Fix display and clarity of workflow run step results, improving their presentation and usability. #4338
• BREAKING change by renaming 'vnext' to 'workflow' and the previous 'workflow' to 'legacy workflow', along with related test updates. #4358

Memory

• Fix agent messages containing working memory references were not saved to the database by filtering out those references instead of skipping the messages entirely. #4303
• Add new MessageList class that unifies and converts various message types (UIMessage, Message, CoreMessage, Memory) into a consistent storage format, laying the groundwork for future integration with agents and support for AI SDK v5 UIMessages. #4287
• BREAKING CHANGES to the Memory module by removing default store/vector/embedder fallbacks, inheriting storage from the Mastra instance if set, updating memory defaults, and revising related documentation and samples. #4309

Storage

• Validation and parameterization across clickhouse, cloudflare-d1, postgres, and libsql to enhance SQL injection protection. #4244
• BREAKING CHANGE: The use of positional arguments in all public vector store functions, requiring object parameters instead for consistency ahead of a full deprecation on May 20th, 2025. #4284
• A new DynamoDB storage backend for Mastra using a single-table design with ElectroDB, supporting all core operations and optimized for serverless environments. #4013
• BREAKING CHANGE to all vector stores by removing positional arguments from public functions and constructors, replacing deleteIndexById and updateIndexById with deleteVector and updateVector, and cleaning up deprecated variables and tests. #4347
• BREAKING CHANGE The direct libsql dependency from @mastra/core, eliminating built-in LibSQL storage implementations and requiring users to explicitly install and configure @mastra/libsql for LibSQL storage support. #4368

MCP

• New list and get routes for MCP servers according to the latest spec, introduces server versioning and optional parameters for backwards compatibility, allows custom server IDs, and includes comprehensive test coverage for the new features. #4243
• An issue where all input fields were incorrectly coerced to required in MCP and core modules, ensuring optional arguments remain optional and preventing breakage in many MCP servers. #4341
• The documentation for Apify and adds corresponding tests. #4366
• The MCP Servers list page and adds a new MCP server details page to the Playground. #4377

CLI / Playground

• Handling broken images in the playground. #3509
• Playground agent settings are preserved across page refreshes. #4227
• Support for browsing, inspecting, and executing tools on mastra MCP Servers directly from the playground UI, including new backend routes to enable these features. #4279
• Fix CORS issues in playground development by adding a proxy to route API requests to the mastra server. #4274
• Improve the user experience and interface of the agents' right sidebar in the playground. #4267
• Fix UI by changing the empty state design for threads. #4288
• Add runtime context page and add formatting, copy-to-clipboard functionality, syntax highlighting, and a documentation link. #4293
• Add tools page UI and adds a search bar for improved usability. #4298
• Fix insufficient spacing in the tool list on the agent page. #4301
• Fix sidebar's user interface for improved usability and appearance. #4334
• Fix issue where the runtime context was not handling overflow scrolling correctly. #4348
• Add missing x-mastra-dev-playground headers to the local tracing exporter and related components. #4357
• Adjust UI to display the agent, workflow, or tool ID next to the copy button for easier identification and copying. #4361
• Make tools not used by agents still discoverable in the playground. #4364
• Fix informational message at the bottom of the screen when memory is not enabled. #4372

Client SDK - JS

• Add the telemetry option to the client SDK's streamParams configuration. #4247
• Omit non-serializable options from agent stream and generate operations, ensuring only serializable data is included. #4250
• Fix trailing slash from the mastraClient baseUrl to standardize URL formatting. #4268
• MastraClient to accept plain objects as runtimeContext. #4272

Core

• @mastra/core to peerDependencies to help deduplicate versions, requiring users to include it in their projects and introducing a breaking change. #3488
• Agent async onFinish and onFinishStep callbacks are properly awaited in the streaming flow, preventing the stream from closing before these callbacks complete and allowing all intended data to be sent. #4148
• Updated Prettier configuration and fixes code formatting issues to ensure lint checks pass. #4189
• Make 'nodemailer' as an external dependency to the mastra bundler. #4295

Server/Deployer

• Add 'all' endpoint to the server route. #4108
• The Vercel deployer can properly handle POST, PUT, DELETE, and OPTIONS HTTP requests. #4275
• Add Mastra server fallback hostname to undefined when not set. #4229

Observability

• Fix traces waterfall visualization to replace the previous stacked progress bars. #4206
• UPGRADED OpenTelemetry JS SDK to version 2.x and excludes additional redundant telemetry storage traces. #4294
• BREAKING CHANGE: Pino logging out of @mastra/core into @mastra/loggers and replaces it in the core with a simpler ConsoleLogger. #4339

RAG

• Fix parsing error related to the fastembed token #4209. #4246
• Add 'sources' array field to the output schema of the vector query and graph RAG tools, enabling users to retrieve detailed results for each query. #4302
• Fix TypeScript error by allowing the return types of createVectorQueryTool and createGraphRAGTool to be correctly inferred, resolving issues with exactOptionalPropertyTypes. #4307
• Fix floating point precision errors in rerank weight summation by using big.js to ensure weights add up exactly to 1. #4322

Tools

• Fix Tool compatibility issues by properly handling ZodOptional and removing unsupported ZodAny types for OpenAI reasoning models. #4306

Auth

• An experimental authentication and authorization system with configurable token verification, rule-based access control, and example usage, along with unit tests and default utilities. #4342

Getting Started

• Ensure create-mastra script to ensure it matches version tags exactly, preventing incorrect matches such as defaulting to the alpha tag when the core version has not been updated. #4256

AGUI

• Move AGUI component from the client side to the server side. #4241

Voice

• Support for passing a runtime context to the OpenAI realtime voice API, enabling tools to access contextual data during realtime sessions. #4305