Mastra Release - 2025-09-05

Agents

• Added a Mastra template for a financial modeling agent that integrates with Google Sheets via Composio, enabling professional financial models and analysis directly in Sheets. #7080
• Updated the Agents Overview documentation to clearly show the use of experimental_output and removes references to structuredOutput in example code. #6854
• Updated the MastraEmbeddingModel and implemented a TypeScript-related workaround. #7124
• Added an agent builder package that enables the creation of mastra projects from templates. #7106 [IMPORTANT]
• Ensured that the abort signal is correctly piped to the agent stream and generate functions in the Mastra server. #7259
• Fixed an issue in @mastra/core where initial user messages with empty content were incorrectly filtered out, potentially resolving issue #7231. #7317
• Ensured that when using streamVNext with format: 'aisdk', the onFinish callback now correctly receives all assistant response messages, fixing an issue where these messages were previously missing. #7327
• Made minor adjustments to the agent-builder package's build process and updates its TypeScript peer dependency. #7330
• Updated the documentation to add information about suspend feedback. #7318
• Fixed a Base64 decoding error when handling images with Google Gemini models by properly converting image data types and refactoring image conversion logic into reusable utilities. #7396
• Added support for passing public URLs of large documents to the LLM in Multi Modal mode by implementing a server endpoint to verify document content types. #7244
• Added a body sanitization utility to agent handlers to remove disallowed keys like 'tools' from request bodies, preventing client-sent properties from interfering with LLM provider tool handling. #7002
• Enhanced the agent builder workflow by adding model selection, environment variable support, improved .gitignore handling, hot reload disabling, branch creation notices, and persistent installation state, while supporting both v1 and v2 models. #6812 [IMPORTANT]

CI / Tests

• Set up the Renovate configuration and upgrades dependencies to improve project maintenance. #7034
• Added comprehensive tests for the StoreOperationsInMemory.batchInsert method, verifying correct ID assignment, edge case handling, and increasing code coverage by 15 lines. #7107
• Added comprehensive tests to ensure that convertFullStreamChunkToUIMessageStream correctly transforms tool-output stream parts into UI message format, accurately mapping fields and preserving all output properties. #7130
• Added comprehensive tests for the CohereRelevanceScorer, covering API request formatting, authentication, success and error scenarios, edge cases, and increases code coverage by 29 lines. #7214
• Added the CI workflow for the agent builder. #7316
• Removed Verdaccio authentication from the CI setup to eliminate intermittent npm authentication errors and make end-to-end tests more reliable. #7322
• Fixed end-to-end test installation issues by ensuring the correct version is used. #7329
• Added a timeout to the monorepo test to improve test reliability. #7366
• Fixed the build process for the cloud ai-trace package to enable direct exports from '@mastra/cloud/ai-tracing'. #7384
• Updated the peer dependencies for various packages. #7394
• Removed the changeset plugin from the project. #7407
• Fixed a previously failing scorer test to ensure it passes. #7483
• Added validation logic for peer dependencies. #7364

CLI / Playground

• Fixed the root-level dev:playground command to ensure it works correctly. #7044
• Improved the log output of the 'mastra dev' CLI command for improved readability and clarity during development. #7046
• Ensured that the playground client and API requests use the same baseUrl host, addressing issue #7099. #7115
• Updated 'mastra start' to load environment files (including custom ones) and deprecates the redundant 'mastra build --env' flag. #7218
• Updated the documentation to include references to the Mastra playground. #7258
• Fixed the create-mastra command by replacing the unsupported yarn --save-dev flag with the cross-compatible -D alias to ensure successful project creation across package managers. #7358
• Added support for Mistral AI as a default provider in the CLI, improving options for users, especially in France and the EU, and refines model selection logic for better maintainability. #7268
• Fixed a bug where the playground workflow graph was broken when the workflow started with a branch. #7434

Client SDK - JS

• Moved the 'zod' package from dependencies to peerDependencies in the Inngest project. #7093
• Enhanced the ai-sdk stream output to render tool-output using a custom UI, enabling support for custom AI SDK tool outputs such as weather data. #7129
• Added the new @mastra/ai-sdk package, enabling easy creation of custom /chat routes for use with the useChat hook. #7263
• Updated the client SDK README to document the new streamVNext and generateVNext functions. #7379
• Added support for AI SDK v5 models in the runExperiments functionality. #7081
• Fixed the import statement for the ai-sdk library. #7431
• Removed the unused ag-ui client from the client-js codebase. #7371

Core Platform Components

• Fixed an issue where the onFinish callback in defaultStreamOptions for an agent was being overridden by the telemetry decorator, ensuring custom onFinish handlers are now respected. #7386

Deployer

• Fixed a vulnerability related to Azure. #7213
• Suppressed non-error package manager logs during dependency installation in 'create-mastra' and 'mastra build', consolidates the logic into shared utilities, and adds type-safety. #6946
• Added deployer, server, and client-js handlers to support agent builder actions in the agent builder template. #7136
• Fixed the build process for the cloud ai-trace component. #7385

Developer Tools & UI

• Improved focus outline styles in the local playground for a more consistent user experience. #7076
• Added fixes and improvements related to outline functionality. #7101
• Removed all hotkey references to resolve issues with child processes. #7100
• Fixed an issue with the chat outline. #7210
• Added support for file download functionality. #7127
• Ensured that the 'hono' package is not treated as an external dependency during development. #7207
• Updated the templates entry in the _meta.ts file for improved organization. #7241
• Added a padding-bottom workaround to the DynamicForm in ToolExecutor to ensure the submit button remains fully visible when the form is long and scrollable. #7265
• Added deprecation warnings and legacy methods to the generate and stream functions in preparation for upcoming breaking changes. #7269
• Ensured environment variables are loaded before starting the watch process in mastra dev, allowing them to be available at bundle time. #7357

Evals

• Set up a context precision scorer and updates the relevant documentation. #6978
• Added support for initializing and registering scorers on the Mastra instance, enabling users to override scorers when using agent methods like generate and stream. #7039 [TIER2]
• Set up a prompt alignment scorer and updates the relevant documentation. #7105
• Set up a noise sensitivity scorer and updates the relevant documentation. #7077
• Fixed passing the tracing context to scorer runs to fix a database error caused by a missing column, with plans to reintroduce the context after updating storage adapters. #7397
• Applied a follow-up fix for issues related to scorers. #7401
• Added support for passing tracingContext to scorer runs and introduces input validation before saving scores. #7437
• Set up a context relevance scorer to enhance the system's ability to evaluate and rank contextual relevance. #7014

Examples

• Updated Next.js in the travel-app example from version 15.4.5 to 15.4.7, incorporating backported bug fixes including improved router handling, error page URL management, and font asset handling. #7226
• Updated the Next.js dependency in the voice-memo-app example from version 15.3.1 to 15.4.7, incorporating various bug fixes and improvements from recent Next.js releases. #7232
• Added a template for an intelligent agent that analyzes Gmail messages for meeting requests and automatically schedules Google Calendar events with all email participants using Mastra. #7208
• Updated the documentation by adding frontmatter to the memory examples. #7374

MCP

• Fixed MCPClient to properly handle Zod v4 schemas when retrieving tools, addressing issue #7092. #7114
• Improved schema compatibility for v2 language models by not setting 'model.supportsStructuredOutputs', ensuring the correct compatibility layer is used. #7116
• Fixed a compilation error by ensuring zod.toJsonSchema is only called when available, improving compatibility with strict compilers and different zod versions. #7121
• Fixed an error when using AI tracing with structured output by replacing object spread with a Proxy in model wrapping to preserve all model properties. #7203
• Updated the codebase to allow provider options to be passed through to relevant components or functions. #7217
• Fixed an issue where providerOptions were not passed in streamVNext, enabling reasoning-delta chunks to be received in the stream. #7323
• Fixed a security issue by validating that the resolved documentation file path does not escape the base directory, preventing path traversal attacks. #7238
• Added validation to ensure that URLs submitted to the docs MCP server via fetchBlogPost belong to the same domain as BASE_BLOG_URL, addressing a security and performance issue. #7237
• Fixed persistent import errors with z.toJSONSchema in the core and schema-compat modules, addressing issues reported in #7283 and affecting the openapi-spec-writer example. #7350
• Added a createMCPTool helper to ensure correct types are available in the execute function for MCP server tools. #7383
• Updated the MCP server to properly handle log level changes and adds a handler for logging/setLevel requests, ensuring compatibility with WSL and alignment with the MCP specification. #7349
• Updated MCPTool to be a generic type, enabling parameter typing for improved type safety. #7389
• Refactored MCPTool to be a generic class for improved parameter type safety. #7391
• Removed all references to Dexter MCP, as it is no longer in use. #7487

Memory

• Added comprehensive tests for the InMemoryMemory.updateResource method, covering both resource creation and update scenarios and increasing code coverage by 29 lines. #7315
• Ensured that an error is thrown if a falsy or empty string threadId is passed to message-fetching methods, clarifying that these methods require a valid threadId and cannot be used for cross-thread searches. #6675
• Fixed an ordering issue so that output processors (like PII redaction) are applied to messages before they are saved to memory, ensuring only processed content is stored, and adds integration tests to verify the behavior. #7445
• Fixed a bug in the Memory.query() method so that pagination parameters are now correctly handled, returning only the requested page of messages instead of all messages. #7486

Networks

• Fixed broken links in the documentation. #7260
• Fixed a bug where V2-to-V1 message conversion duplicated content across split messages by ensuring each message part displays its unique text, and adds comprehensive tests to prevent regression. #7321
• Added a tripwire chunk to the streamVNext full stream. #7392

Observability

• Added a new AI Tracing span type specifically for events. #7027
• Added a configurable DefaultExporter for AI Tracing with support for realtime, batch-with-updates, and insert-only modes, enhancing observability options for different storage providers. #7085
• Filtered out excessive low-level OpenTelemetry spans to prevent database storage issues and ensure only relevant traces are exported. #7091
• Added support for OTEL exporter environment variables for OTLP headers, aligning the implementation with the documentation. #7086
• Removed HTTP instrumentation root spans from trace queries and promotes their direct child spans as new roots to improve trace filtering and consistency with cloud practices. #7215
• Added and propagates tracingContext throughout all components (agents, workflows, processors, scorers, etc.), ensuring unified trace generation for each AI event and enabling custom span creation by users. #7274
• Updated the default AI observability exporter to support event-type spans that only have an 'end' event, fixing errors related to out-of-order span updates. #7353
• Disabled creating individual event spans for each LLM chunk in streaming responses to reduce verbosity in ai-observability. #7361
• Added a CloudAITracingExporter to stream AI trace data in batches to the Mastra Cloud observability platform, extracting team and project IDs from JWT access tokens. #7376
• Initial release of the BraintrustExporter for ai-observability, providing functionality similar to the existing LangfuseExporter. #7419

Prod analytics

• Fixed vulnerabilities by removing a custom header, fixing JSON issues in the client-js workflow, and updating the AI SDK dependency in the JavaScript client library. #7224
• Enhanced the Langfuse exporter by adding robust event span handling, circular reference protection, and improved span data cleaning to prevent JSON serialization errors and database failures, while unifying span lifecycle management and improving performance. #7266
• Updated the LangfuseExporter configuration by allowing parameters to be of type 'string' or 'undefined', enabling users to pass environment variables without using the '!' operator. #7417

RAG

• Updated the embedding model by updating MastraEmbeddingModel, removing unnecessary embeddings, and fixing vector query logic, along with a TypeScript workaround. #7125

Storage

• Fixed a module import error by updating the libsql store's peer dependency to require @mastra/core v0.15.0 or higher, ensuring compatibility with the new AI_SPAN_SCHEMA export and observability features. #7200
• Fixed an issue by ensuring that existing PostgreSQL indexes are not recreated. #7326
• Fixed an issue where text deltas from LLM providers were incorrectly stored as separate parts, ensuring they are now combined into a single text part for cleaner message formatting. #7382

Tools

• Fixed the issue of undefined tracingContext in tool executions for AI tracing and cleans up the related tool wrapping code. #7109
• Added support for passing providerOptions to the createVectorQueryTool and createGraphRAGTool functions, enabling users to customize embed function options. #7120
• Improved tool validation by correctly handling cases where input data is nested under 'context' or 'inputData' keys, preventing validation failures when users use these reserved keys. #7216
• Added the missing API endpoint to retrieve an agent tool by ID, enabling client SDK calls like agent.getTool("get-weather") to function correctly. #7250
• Fixed an issue by adding missing tool options to the createTool function. #7267
• Added a workflow badge and inner graph display to agents that have registered a workflow, enhancing their visual representation in threads. #7416
• Added and updated tests related to tool retry functionality. #7435
• Added type inference helpers to @mastra/core, enabling seamless TypeScript compatibility between Mastra tools and AI SDK v5 UI components by extracting input and output types for improved type safety. #7441

Website

• Fixed a broken breadcrumb link on the agents/tools page. #7138
• Fixed a vulnerability related to cookies, though specific implementation details are not provided. #7220
• Fixed redirect issues by adding locale awareness to all redirects. #7368
• Fixed a production issue by updating the Nextra config and sidebar links to correctly append the locale to links, preventing path duplication. #7440

Workflows

• Enhanced RunExperiments to support workflows, enabling experiments to be run and scored at both the workflow and individual step levels. #7025
• Updated the documentation to include error-handling information for workflows. #7074
• Added a new 'maxSteps' feature. #7030
• Added native flow control options—including concurrency, rate limiting, throttling, debouncing, and priority queuing—to Mastra workflows by extending WorkflowConfig to support Inngest's advanced execution management features. #7090
• Added a workflow builder feature for creating workflows in the agent-builder component. #7223[TIER2]
• Fixed a bug where private members could not be accessed on wrapped workflow and agent objects by ensuring proxy methods are properly bound to their targets, resolving context loss issues when calling methods like agent.getLLM(). #7246
• Improved error handling in Mastra workflows by ensuring the original stack trace is preserved when wrapping errors, and refactors duplicated error processing logic into a single method. #6966
• Updated documentation to include 'await' in writer calls for improved clarity and correctness. #7256
• Updated the documentation by adding an example of using curl to run workflows. #7270
• Updated documentation to use 'return await suspend' in workflows. #7262
• Enhanced GetWorkflowRunExecutionResult to include detailed information about nested workflow steps, ensuring all steps (including those in nested workflows) are returned in the response. #7272
• Improved workflow streaming by renaming events, enabling retrieval of all workflow events when used as a tool from an agent, ensuring backwards compatibility between .stream() and .streamVNext(), updating event types, fixing usage tracking for agentic loop executions, and adding writer support to workflows as a tool. #7355
• Disabled the import of agent-builder workflows and routes due to performance slowdown issues, pending further investigation. #7388
• Added the .streamVNext() method to enable streaming of agent events within workflows, with future updates planned for additional streaming formats and execution engines. #7413
• Updated the system to support both the new vNext streaming event format and the existing .stream() event types for workflows. #7424
• Fixed a TypeError by ensuring workflows can correctly access the __registerMastra function when used as a step. #7484