Mastra Release - 2025-10-01

We are excited to announce the release of our new model router and model fallbacks! You can now choose any model provider and model without the need to install or import it. If one model is not functioning properly, you will automatically be able to fallback to another model.

Agents

Step identification by including description and component key when steps are created from agents or tools, and updates related tests. #8151
Unspecified fixes as described in the title and template, but lacks details about the specific changes made. #8286
The trace scoring logic to eliminate duplication in building agent payloads and updates related tests. #8280
The agent to return the selection reason as the result when it cannot route and pick a primitive. #8308
TypeScript type inference issues by making the 'suspend' property optional in ToolExecutionContext and resolving module resolution conflicts for DynamicArgument, improving tool usability and type safety. #8305
The routing agent to throw an error if the required memory parameter is not provided. #8313
A race condition in the stream pipeline by adding controller state checks before enqueueing data, preventing errors from stale callbacks attempting to write to a closed ReadableStreamDefaultController during sequential agent tests. #8186

CLI / Playground

Rremoved the legacy workflow from both the playground and client-js components. #8017
Model fallback functionality to the playground as a new feature. #7427
The playground UI's stream handling by ensuring correct part ordering and robustness when processing streamed assistant messages, including adding empty messages and text parts as needed and properly handling content types. #8234
The playground to display which model from the fallback list was successfully used. #8167
The playground's model picker to use the new model router, adding provider connection status indicators, info links to provider docs, improved warning and error handling, and preserving drag-and-drop reordering for multi-model setups. #8332
The network label when memory is not enabled or when the agent has no subagents, addressing a UI bug. #8341

Client SDK - JS

A bug in the client-js SDK that caused duplicate storage of the initial user message when client-side tools were executed, ensuring only assistant responses and tool results are sent back to the server instead of resending the original user message. #8187
The useMastraClient hook and its provider have been moved to the React package. #8203
Missing traceId output when using the aisdk format and disables tracing in input/output processors to prevent unwanted traces. #8263
The React SDK to convert network chunks into UIMessage objects, enhancing how network data is handled in the UI. #8304

Deployer

A bug where a randomUUID call was leaking into the global scope of the Cloudflare worker during the mastra build process by preventing it from being called at import time. #8105
An environment variable, MASTRA_HIDE_CLOUD_CTA, to allow hiding the Mastra cloud deploy button, requiring a full server restart to take effect. #8137
Build and unit test issues in the Cloudflare deployer, adds end-to-end tests, and resolves a compatibility bug with @mastra/pg. #8163
The deployer code to update the description for starting a workflow run via the /api/workflows/{workflowId}/start endpoint. #8158
Issues with native dependencies in bun monorepos for the deployer by correcting the bun pack process. #8201
Mastra Cloud to version 0.1.15, including the removal of a custom header from the JavaScript client, a workflow fix for JSON issues, and an AI SDK dependency update. #8134
The installation process for indirect external dependencies in the Mastra build system. #8145
An end-to-end (e2e) job for the deployere component. #8211
Mastra Cloud to version 0.1.15 to resolve a peer dependency issue with @mastra/cloud. #8276
Workspace path handling on Windows by introducing a utility to normalize path separators, resolving issues with workspace detection and comparisons. #7943
Support for Netlify Gateway by introducing a NetlifyGateway class, updating gateway and OpenAI-compatible classes for dynamic URLs and token generation, and enhancing model ID resolution. #8331

Evals

Conditional chaining to scorer.agentNames to prevent errors when accessing potentially undefined properties. #8199
The score types to allow input and output to be any type. #8153
Server APIs to retrieve all scores by trace and span ID, along with corresponding test updates. #8237

MCP

The generateVNext function to correctly return a stream response for the tripwire case and removes unnecessary special handling for tripwire responses. #8122
Comprehensive and accurate TypeScript types to the streamVNext code path, aligns return types, removes dead code, and improves overall type safety and code clarity. #8010
Core error processing to safely parse error objects using safeParse. #8312
A model router system to @mastra/core, allowing users to specify any OpenAI-compatible provider and model using simple magic strings (e.g., 'openai/gpt-4o'), with automatic provider config resolution and support for custom providers, streamlining model selection and integration. #8235

Networks

Agent networking failures with working memory by correctly passing and fetching memory tools, updates prompts to improve agent tool usage, and renames resourceId/resourceType to primitiveId/primitiveType for clarity. #8157
Issues with the network chunk type and updates the working memory test. #8210
Error processing by ensuring that useful error information in stream error objects is no longer masked. #8270
The network callout to mention that memory is required. #8315

Observability

A new LangSmith observability package, adapted from the Braintrust implementation, to enhance monitoring and tracing capabilities. #8160
The initial release of an OpenTelemetry exporter to enable AI observability. #8273

Storage

Optional SSL support to PostgreSQL connection string configuration, improves type safety in config validation, and enhances error handling for invalid configurations. #8178
A separate spanId column to the scores table to enable fetching scores by both traceId and spanId, instead of storing both under the traceId column. #8154
Full AI tracing support to the PostgreSQL storage adapter, updates SpanType to use strings instead of integers across all stores, and ensures timestamps are set by the database rather than the exporter. #8027

Tools

Type definitions to use structural typing for Zod schemas, ensuring compatibility with both Zod v3 and v4 in tool schemas, and adds CI tests to prevent future regressions. #8150
A concise documentation (mini doc) for the HITL (Human-in-the-Loop) tools. #8205
A bug by ensuring that ToolInvocationOptions are correctly used in the execute parameters of createTool. #8206
A bug where streaming would hang for client-side tools that were not self-executing by ensuring the stream properly closes when no client tools are run. #8272

Voice

The speak method in openai-voice now destructures the options parameter to extract key properties while allowing additional OpenAI voice parameters to be passed through, improving flexibility for callers. #8228
Support for multiple Google Voice authentication methods—including API keys, service account key files, and inline credentials—enables use of Application Default Credentials (ADC), and updates the documentation accordingly. #8086

Workflows

Support for passing register options to the Inngest serve function, enabling users to configure additional registration settings when serving Mastra workflows. #8139
Optional Zod-based input and resume data validation to workflow steps, controlled by a new validateInputs option, and updates tests accordingly. #7779
Support for passing tracing options when starting or resuming workflows via the hono server APIs and client SDK. #8277
An issue where instructions passed as an object (instead of a string) could not be resolved in the playground, allowing both notations as valid input. #8284
A workflow transformer to the AI SDK, allowing seamless integration of Mastra workflows with Vercel's useChat hook in React applications by automatically converting workflow responses into the required format. #7829
Support for passing metadata to traces via tracing options in workflow stream and streamVNext handlers. #8278

Changed Packages

🦋 New tag: @mastra/ai-sdk@0.0.5
🦋 New tag: @mastra/client-js@0.14.1
🦋 New tag: @mastra/react@0.0.2@mastra/deployer-cloud@0.19.1
🦋 New tag: @mastra/deployer-cloudflare@0.14.4
🦋 New tag: @mastra/deployer-netlify@0.13.4
🦋 New tag: @mastra/deployer-vercel@0.12.4
🦋 New tag: @mastra/longmemeval@0.1.23
🦋 New tag: @mastra/braintrust@0.1.5
🦋 New tag: @mastra/langfuse@0.0.10
🦋 New tag: @mastra/langsmith@0.0.1
🦋 New tag: @mastra/otel-exporter@0.0.2
🦋 New tag: @mastra/agent-builder@0.0.7
🦋 New tag: mastra@0.13.4
🦋 New tag: @mastra/cloud@0.1.17
🦋 New tag: @mastra/core@0.19.1
🦋 New tag: create-mastra@0.13.4
🦋 New tag: @mastra/deployer@0.19.1
🦋 New tag: @mastra/evals@0.13.9
🦋 New tag: @mastra/loggers@0.10.14
🦋 New tag: @mastra/mcp@0.13.2
🦋 New tag: @mastra/mcp-docs-server@0.13.26
🦋 New tag: @mastra/mcp-registry-registry@0.10.17
🦋 New tag: @mastra/memory@0.15.4
🦋 New tag: @mastra/playground-ui@6.2.4
🦋 New tag: @mastra/rag@1.2.7
🦋 New tag: @mastra/server@0.19.1
🦋 New tag: @mastra/google-cloud-pubsub@0.1.7
🦋 New tag: @mastra/astra@0.11.11
🦋 New tag: @mastra/chroma@0.11.11
🦋 New tag: @mastra/clickhouse@0.15.3
🦋 New tag: @mastra/cloudflare@0.12.3
🦋 New tag: @mastra/cloudflare-d1@0.13.3
🦋 New tag: @mastra/couchbase@0.11.11
🦋 New tag: @mastra/dynamodb@0.15.4
🦋 New tag: @mastra/lance@0.3.3
🦋 New tag: @mastra/libsql@0.15.0
🦋 New tag: @mastra/mongodb@0.14.3
🦋 New tag: @mastra/mssql@0.4.3
🦋 New tag: @mastra/opensearch@0.11.12
🦋 New tag: @mastra/pg@0.17.0
🦋 New tag: @mastra/pinecone@0.11.11
🦋 New tag: @mastra/qdrant@0.11.14
🦋 New tag: @mastra/s3vectors@0.2.4
🦋 New tag: @mastra/turbopuffer@0.11.11
🦋 New tag: @mastra/upstash@0.15.3
🦋 New tag: @mastra/vectorize@0.11.12
🦋 New tag: @mastra/voice-azure@0.10.14
🦋 New tag: @mastra/voice-cloudflare@0.11.7
🦋 New tag: @mastra/voice-deepgram@0.11.7
🦋 New tag: @mastra/voice-elevenlabs@0.11.7
🦋 New tag: @mastra/voice-gladia@0.11.7
🦋 New tag: @mastra/voice-google@0.11.7
🦋 New tag: @mastra/voice-google-gemini-live@0.10.13
🦋 New tag: @mastra/voice-murf@0.11.7
🦋 New tag: @mastra/voice-openai@0.11.7
🦋 New tag: @mastra/voice-openai-realtime@0.11.7
🦋 New tag: @mastra/voice-playai@0.11.7
🦋 New tag: @mastra/voice-sarvam@0.11.7
🦋 New tag: @mastra/voice-speechify@0.11.7
🦋 New tag: @mastra/inngest@0.14.2

mastra-ai/mastra @mastra/core@0.19.1 2025-10-01 on GitHub