npm / mastra
mastra
What changed in mastra 1, from its official release notes, upgrade guides and advisories. Also covers @mastra/agent-builder, @mastra/ai-sdk, @mastra/arize, @mastra/client-js, @mastra/codemod, @mastra/convex, @mastra/core, @mastra/deployer-cloudflare, @mastra/editor, @mastra/elasticsearch, @mastra/evals, @mastra/memory, @mastra/observability, @mastra/playground-ui, @mastra/rag, @mastra/react, @mastra/schema-compat, @mastra/server. Sources checked 2026-10-19.
15 breaking5 security58 new APIs and options1 performance16 behavior and defaults3 tooling26 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initmastra 1124 changes
Breaking changes 15
Vector document IDs now come from Elasticsearch _id; stored id fields are no longer written, which affects code relying on source.id.
The Hono adapter returns HTTP 400 with a structured error for invalid POST JSON instead of HTTP 200, preventing workflows from starting with undefined input.
The Hono adapter returns HTTP 400 with a structured error for invalid JSON POST bodies instead of accepting them with HTTP 200.
Memory API endpoints now prioritize this middleware-reserved context key over client-provided values for secure user isolation.
Memory API endpoints now prioritize this middleware-reserved context key over client-provided values for secure user isolation.
A configured route prefix now replaces the default /api prefix instead of being prepended to it.
Adapters and
@mastra/serveradd explicit per-route authentication controls, with routes protected by default.Built-in API routes now declare whether authentication is required; routes default to protected, and setting requiresAuth: false makes a route public.
Stored agent records now contain metadata only; configuration lives in versioned snapshot rows, and
ownerIdis renamed toauthorId.Stored agent records now contain metadata while configuration lives in version snapshots; ownerId is renamed to authorId, memory becomes a record, and status is added.
Stored agent records now contain metadata only; configuration lives in version snapshots, and list endpoints return resolved agents. The ownerId field is renamed to authorId.
Stored agent records now hold metadata while configuration lives in version snapshots; resolved agents combine the record with active-version configuration. Inputs are flattened, memory is an object, and ownerId is renamed to authorId.
Stored agent records now hold thin metadata while configuration lives in version snapshots; the change also adds status, renames ownerId to authorId, changes memory to an object, and flattens create/update inputs.
The Google embedding model was removed from the model router; use
google/gemini-embedding-001instead.A codemod transforms getInitData() calls to getInitData<any>() to restore the previous behavior after its return type changed from any to unknown.
Security 5
Sensitive observability credentials in tracingContext are excluded from tool execution error logs.
Custom routes with requiresAuth: true enforce authentication in dev mode, and routes with path parameters correctly respect requiresAuth: false.
Custom routes registered with requiresAuth: true now enforce authentication in development mode.
Built-in API routes expose requiresAuth, defaulting to true; set it to false to make a route public.
A unified API provides filesystem operations, sandboxed execution, search, and SKILL.md discovery with safety controls.
New APIs and options 58
Look up processors by ID on an Agent.
Elasticsearch connections accept authentication configuration, including API key, basic, and bearer authentication.
The project creation wizard can optionally install official Mastra skills and lets users choose an agent.
A utility helps extract tool results from scorer output for use in dynamic scoring context.
The hallucination scorer accepts a getContext hook to resolve scoring context dynamically at runtime.
A utility type for schema input type inference is available.
A utility type for schema output type inference is available.
A new package stores, versions, and resolves agent configurations from a database, including dependencies from the Mastra registry.
The server adds proxy endpoints for searching, browsing, previewing, installing, updating, and removing skills from skills.sh.
Workspace filesystem errors expose a MastraClientError with status and body properties; not-found errors return 404 instead of 500.
Set observationalMemory: true to enable a three-tier memory system that compresses conversation history into observations and reflections.
A manual API for triggering observation outside the normal agent loop is available.
Processor state can be persisted across loop iterations.
Processors can emit custom stream events using ProcessorStreamWriter.
ToolSearchProcessor's search configuration accepts minScore to filter results below a score threshold; the documented default is 0.
ToolSearchProcessor's search configuration accepts topK to set the number of returned results; the documented default is 5.
Workspace accepts a custom search index name; default index names now use underscores to work with SQL-based vector stores.
Non-interactive project creation can install skills by passing comma-separated agent names with --skills.
Studio adds an Add Skill dialog to browse, preview, install, update, and remove skills from the skills.sh registry.
A type is available for schemas implementing both validation and JSON Schema conversion.
Agents can search for and load tools on demand through built-in meta-tools, reducing context usage when working with large tool libraries.
Convert Zod, JSON Schema, or AI SDK schemas to Standard Schema format.
The model loop stream accepts
activeToolsto control which tools are available during LLM execution.Network calls can receive an abort signal and an
onAbortcallback so callers can cancel execution and handle aborts.Dynamic agent management adds CRUD operations, version history, compare and restore capabilities, and automatic versioning on updates.
MastraClient accepts a custom API route prefix for servers deployed behind non-default paths; the default remains /api.
MastraClientProvider accepts apiPrefix for connecting to servers with custom API route prefixes; it defaults to /api.
Stored agents can be created, edited, and deleted through CRUD APIs, with version history, compare and restore capabilities, and optional automatic versioning.
Trace results include a status of
success,error, orrunning, making trace state easier to filter and display.The response now includes a status field indicating whether a trace succeeded, errored, or is still running.
The listTraces response now includes a status indicating whether a trace succeeded, errored, or is still running.
The listTraces response now includes a status field indicating whether each trace succeeded, errored, or is still running, so callers can filter traces without deriving state from other fields.
The client adds workspace methods for files, skills, references, and search.
Set MASTRA_SKIP_PEERDEP_CHECK=1 to skip the CLI peer dependency check.
The studio command accepts --server-api-prefix to connect to servers with custom API route prefixes.
Workspace client methods support workspace discovery, filesystem operations, skill management, and indexed-content search.
Server adapters accept MCP options, including
serverless: true, for stateless MCP HTTP transport in serverless or edge environments.Server adapters accept mcpOptions.serverless to run MCP HTTP transport without session state, supporting isolated serverless requests.
Server adapters accept mcpOptions; setting serverless: true enables stateless MCP HTTP transport for serverless environments.
Providers using non-default AI SDK packages are routed to their correct SDK instead of falling back to
openai-compatible; Cerebras, Together AI, and DeepInfra are added as native SDK providers.When enabled, working memory is provided as context but the
updateWorkingMemorytool is unavailable.When readOnly is true, working memory is provided as context but the updateWorkingMemory tool is unavailable.
Provides access to all request context values, including validated values.
Tools, agents, workflows, and steps can define a Zod schema to validate request context at runtime and provide typed access.
Added type support for requestContextSchema.
The Inngest integration adds requestContextSchema type support.
Added type support for requestContextSchema.
Adds an option to connect Mastra Studio to a server using a custom API prefix.
Stored agents gain CRUD and version-management APIs, client SDK support, and automatic versioning on updates when enabled, allowing dynamic configuration management and audit history.
Stored agents gain CRUD and version-management operations, including creating, listing, activating, restoring, deleting, and comparing versions, with automatic versioning on updates when enabled.
Agents can be created, edited, deleted, and versioned dynamically through storage, REST endpoints, and the client SDK, with version comparison and restoration.
Developers can configure a custom API route prefix in the Studio UI so Studio works with servers using a custom base path instead of /api.
The workflow-run cancellation hook is now exported from @mastra/react for use in custom applications.
The hook is exported from @mastra/react so custom applications can cancel workflow runs.
A new @mastra/react hook supports streaming, observing, resuming, and time-traveling workflows, with tracingOptions and onError parameters.
The @mastra/react hook supports streaming, observing, resuming, and time-traveling workflows, with tracingOptions and onError parameters.
The playground UI adds components for browsing and viewing workspace files, listing skills, searching workspace content, and viewing skill reference files.
Workspace API endpoints provide workspace discovery, filesystem operations, skill listing and details, references, and indexed-content search.
Performance 1
The Cloudflare deployer stubs out TypeScript to avoid exceeding the Workers 3MB size limit; agent-builder falls back to basic validation when TypeScript is unavailable.
Behavior and default changes 16
Filesystem providers extending MastraFilesystem now automatically receive the Mastra logger for consistent file-operation logging.
Sandbox providers extending MastraSandbox now automatically receive the Mastra logger for consistent command-execution logging.
Custom input processors replace only configured processors; memory and workspace skill tools remain available in generate() and stream().
recall now returns token usage from the vector-search query embedding.
saveMessages now returns aggregated embedding token usage so applications can track embedding consumption.
AI tracing now defaults to a 128KB maxStringLength and maxDepth 8, reducing truncation of large prompts and responses.
Agent voice configuration now accepts any
MastraVoiceimplementation directly, without requiring aCompositeVoicewrapper.bail()accepts any value, allowing workflow steps to exit early with a custom result.AgentBuilder now uses InMemoryStore as a fallback when no storage is provided, allowing Memory operations without explicit storage configuration.
The Agent voice property now accepts
MastraVoiceimplementations directly instead of onlyCompositeVoice.The model router now propagates providers' supported URL patterns, allowing supported file URLs to be passed directly instead of downloaded and converted to bytes or base64.
Custom API routes registered with registerApiRoute are included in generated OpenAPI documentation alongside built-in routes.
The playground no longer hardcodes temperature: 0.5 or topP: 1 in agent settings; agent configuration and provider defaults now determine these values.
Tool approval requests now create MODEL_CHUNK spans containing the tool call ID and name, approval arguments, and resume schema, making approval flows visible for debugging.
Spans inherit entity metadata from the closest non-internal parent, processor spans track input and output separately, streaming emits model chunk spans, and internal framework spans are omitted from exported traces.
Spans inherit entity identifiers from the closest non-internal parent, processor spans track input and output separately, streaming chunks emit model chunk spans, and internal framework spans are excluded from exported traces.
Tooling 3
create mastra can add an AGENTS.md file during project creation, and can optionally add CLAUDE.md.
The CLI checks whether installed @mastra/* packages satisfy each other's peer dependency requirements and warns with upgrade instructions when they do not.
The CLI checks whether installed @mastra/* packages satisfy each other's peer dependency requirements and warns with upgrade instructions when they do not.
Fixes and other changes 26
The moonshotai provider now uses an Anthropic-compatible API endpoint to properly handle reasoning_content for kimi-k2.5.
The China moonshotai provider now uses an Anthropic-compatible API endpoint to properly handle reasoning_content for kimi-k2.5.
An explicit toolChoice of none returned with empty tools is preserved instead of being discarded and defaulting to auto.
Malformed routing-agent JSON is fed back to the routing agent so it can retry instead of crashing the network.
Network workflow runs now receive request context, including user and resource metadata for observability and analytics.
Configured input and output processors are applied to the routing agent, while memory-derived processors are excluded.
Configured output processors are applied to messages before network execution saves them to storage.
Sub-agents no longer receive completion-check feedback from prior network iterations.
Deployer resolves dependency versions accurately in monorepos, including hoisted dependencies, ESM-only packages, transitive workspace dependencies, and deployer-provided packages.
Template merging now converts kebab-case filenames to camelCase correctly and fixes PascalCase and acronym-boundary conversions.
RecursiveCharacterTransformer now supports all languages defined in the Language enum, including languages that previously caused runtime errors during code chunking.
The Convex workflow snapshots table schema now defines the id field required by the by_record_id index, enabling successful Convex deployments.
Swagger UI now uses the correct OpenAPI endpoint URL, /api/openapi.json.
Agent and workflow operations now receive requestContext, preventing tools and nested operations that depend on its values from failing or behaving incorrectly.
Route prefixes are normalized, and a custom prefix replaces the default /api prefix rather than being prepended to it.
Workflow, agent, and tool spans now map to CHAIN, AGENT, and TOOL respectively instead of defaulting to LLM.
PATCH requests now save stored-agent changes correctly instead of failing silently; schema migration and stale-record cleanup restore create and edit flows.
PATCH requests now save stored agent changes correctly; migration handling repairs old snapshot-based schemas and cleans up stale draft records and legacy tables.
Stored agent edits no longer fail silently; PATCH requests save changes correctly, and schema migration repairs legacy snapshot-based versions tables and stale records.
Server handlers now resolve stored and sub-agents as well as registered agents for A2A, memory, scores, tools, and voice endpoints.
suspendedToolRunIdis nullable to fix null handling in tool input validation.The function imports ReadableStream and TransformStream from node:stream/web, fixing TypeScript async-iterator errors with for-await-of loops.
Langfuse and PostHog exporters exclude cached tokens from input counts, report cache read and creation tokens separately, and clamp input counts to prevent negative values.
Validation retries after stripping null values when the initial attempt fails, so optional fields accept null while nullable fields continue to work.
Tags from agent defaultOptions.tracingOptions are now preserved when merging call-site options and passed to observability exporters.
Tags from agent default tracing options are preserved when call-site options are merged and are passed to observability exporters.