2025-09-17 - Mastra Release

Agents

Add better compatibility with Zod v4 in the OpenAI reasoning schema by ensuring default values are correctly handled whether stored as a function (Zod v3) or a value (Zod v4), and adds tests to verify the fix. #7793
Stream markdown as plain text in the agent summary within the agent text view. #7851
Display of the scorers badge in the agent metadata section for improved UI alignment. #7910
Fix destructuring the return value from streamVNext which caused methods and getters to lose their this context by binding all public methods and dynamically binding getters in the constructor #7920
Fix switch logic in the prompt-injection processor. #7951

CLI / Playground

Pass the runtimeContext to client SDK GET methods, following up on a previous PR. #7767
Fix 'mastra init' CLI by displaying an error if run outside a Node.js project and automatically installing the 'zod' dependency if it is missing. #7837
Add Local HTTPS support to 'mastra dev', allowing users to enable it via a command-line flag or configuration option. #7871
Change playground's use-workflows hook to use createRunAsync instead of createRun. #7903
Fix Issues with UI hydration in the traces interface. #7765
Add a Dynamic form rendering to correctly handle Zod intersection schemas, ensuring all relevant input fields are displayed. #7768
Ensure runs list is always up to date by fetching it each time the runs tab is clicked, rather than only on initial mount. #7852
Add default 2px width for AI span elements without an end date to ensure visibility and increases decimal precision to display milliseconds. #7853
Added Scorer components (ScoreDialog, ScoresTools), updates score rendering to use EntryList, adds a simplified code section option, and fixes minor issues. #7872
Each row in the scorers table is clickable and removes an unnecessary data table component. #7915
Add empty state display for scorers, improving the user interface when no scorers are present. #7846
scorer prompts to explicitly display 'null' for empty values instead of rendering an empty component. #7875

Client SDK - JS

Improves the client-js SDK's agents and workflow APIs. #7592
Add dedicated client-js SDK createTool that operates without server dependencies, along with related documentation updates and a changeset. #7781

Core

Ensure the stream deprecation warning is logged only once instead of multiple times. #7905
Remove unnecessary console.log statements from the codebase. #7916

Storage

Ensure 'postgres-store-instance-checker' Babel plugin is only added when '@mastra/pg' is used, fixing an unnecessary plugin inclusion issue. #7832
Support for Google Cloud SQL with IAM authentication by allowing PostgresStore to accept and forward a raw pg.ClientConfig, enabling compatibility with dynamic connection configurations used by the Cloud SQL Node.js Connector. #7523
Ensure database message IDs are preserved and consistently used throughout the UI message stream, allowing clients to accurately track streaming events with their corresponding persisted messages. #7783
Add automatic composite indexes and comprehensive index management features to the PostgreSQL storage adapter, significantly improving query performance and enabling users to create, monitor, and manage indexes for optimized query patterns. #7757
Server cache primitive for resumable streams. #7929

Server

Ensure /api routes are added to Swagger UI overview and document on custom API routes. #7826
A 'requiresAuth' option to custom API routes, allowing explicit control over authentication requirements and ensuring all routes are protected by default unless specified otherwise. #7703
Add a helpful error message to the @mastra/server root index entrypoint to guide users toward using subpath imports. #7762

Bundling

Standardize method signatures, enhance project context handling, improve dependency analysis for monorepos, clean up build configurations, and document code analysis. Some breaking API changes to streamline dev/build processes. #7619 [IMPORTANT]

Agents

Deprecate 'output' property in favor of 'structuredOutput' for the 'generateVNext' and 'streamVNext' methods, maintaining backward compatibility while encouraging migration to the new API. #7750 [IMPORTANT]
Fix critical issues with structured output streaming by ensuring all format handlers consistently preprocess and handle JSON code blocks, resolves enum validation bugs, and adds comprehensive tests to improve reliability and user experience when LLMs wrap JSON responses in code blocks. #7864
Add Model fallback support and configurable retry limits to the vnext agent stream, enabling automatic switching between models and improved error handling. #7126 [IMPORTANT]
Fix usage tokens for both legacy and VNext models #7901
.network() returns a network stream class. #7763
Fix the stopWhen condition in vNext to ensure the correct accumulated step results across iterations. #7862

Networks

Deprecate and remove legacy AgentNetwork and deprecates the old agent network implementation. #7919 [IMPORTANT]

Observability

Refactored the AI tracing implementation to use shared types and standardized naming, improving maintainability with minimal impact on the external API and tests. #7744
The ability to hide internal AI tracing spans by default, introduces a lightweight ExportedAISpan type for exporters, improves parent span handling for exported spans, and significantly enhances the SensitiveDataFilter functionality. #7764
The SensitiveDataFilter to use exact, normalized key matching instead of substring matching, ensuring only true sensitive fields like API keys are redacted while preserving important telemetry data such as token counts. #7840
Fix inconsistent timeline data for spans by adding a client-side patch. #7841
Fix AI span and trace dialogs by removing unnecessary fields, adds start and end times to span details, and updates the time format in the traces list. #7847
Refactored the handling of internal AI spans to intelligently set which spans are marked as internal during workflow or agent creation, rather than determining this during execution. #7876
Fix a critical bug in ai-tracing's DefaultExporter that caused completed spans to be lost as out-of-order after buffer flushes, and adds persistent span tracking with automatic memory cleanup to ensure accurate tracing and prevent memory leaks. #7895
Better error message displayed in observability for storage support missing #7956

RAG

Fix compatibility issue in the rerank function to support AI SDK v5+ and @ai-sdk/openai v2+ models by detecting the model version and using the appropriate generation method, resolving errors with V2 models. #7828

Tools

Add ToolInvocationOptions type alias as a union of ToolExecutionOptions and ToolCallOptions to resolve TypeScript portability issues by abstracting direct references to ai package types in createTool and related interfaces. #7914

Voice

Make voice handler to return a 400 status code with clearer error messages for client-side MastraError instances, instead of a 500 error. #7749

Workflows

Support for resumable streams, allowing stream operations to be retried if the connection is lost. #7949 [IMPORTANT]
Add formatting for AI SDK and improves workflow streams to better handle nested agent events. #7728
Support for associating workflow runs with an optional resourceId, enabling filtering and management of runs by resource across all storage providers, with full backward compatibility and automatic database migrations. #7740
Optional resourceId parameter is properly propagated and persisted throughout the Inngest workflow execution pipeline, enabling workflow snapshots to be associated with a resource. #7792 [TIER2]
Fix bug in the Inngest workflow engine's sleepUntil function by ensuring serialized Date values are properly converted back to Date objects before use, preventing TypeErrors during workflow execution. #7863
Support for user-supplied Inngest functions in the serve/inngestServe function, allowing users to pass custom functions alongside Mastra workflow functions for more flexible integration, while maintaining backward compatibility and type safety. #7900 [TIER2]
Deprecated and removed synchronous createRun() method in favor of the asynchronous createRunAsync(), updating all code, examples, and documentation to enforce async usage and improve consistency across the Mastra ecosystem. #7897 [IMPORTANT]

Changed Packages

mastra-ai/mastra @mastra/core@0.17.0 2025-09-17 on GitHub

2025-09-17 - Mastra Release

Agents

CLI / Playground

Client SDK - JS

Core

Storage

Server

Bundling

Agents

Networks

Observability

RAG

Tools

Voice

Workflows

Changed Packages

mastra-ai/mastra @mastra/core@0.17.0
2025-09-17

on GitHub