Mastra: a TypeScript framework for agents and workflows, reviewed

The problem Mastra solves for TypeScript teams

Assembling an AI feature in a TypeScript codebase usually means choosing a provider SDK, a tool-calling convention, a retrieval layer, a way to persist conversation state, and something to run evaluations. Each of those decisions is small. Together they produce a codebase where the agent loop, the prompt assembly and the persistence layer all know about each other, and swapping a model provider touches everything.

Mastra's answer is to put those concerns behind one interface and keep the whole thing in TypeScript. The README describes it as a framework for building AI-powered applications and agents on a modern TypeScript stack, with model routing across more than 40 providers through one standard interface, agents that use tools and iterate until the model emits a final answer, and graph-based workflows for cases where you want explicit control instead of letting the model decide the order of operations.

The intended audience is narrow and clear: developers already working in React, Next.js or Node.js who want to bundle agents and workflows into an existing app or deploy them as standalone endpoints. If your stack is Python, nothing here is aimed at you.

Agents, workflows and the split between them

The design separates two execution models, and the choice between them is the first real decision you make.

An agent is the open-ended path. According to the README, agents reason about goals, decide which tools to use, and iterate internally until the model emits a final answer or an optional stopping condition is met. You hand over control and the loop decides what happens next.

A workflow is the opposite. Mastra's workflow engine is graph-based, with control flow expressed through `.then()`, `.branch()` and `.parallel()`. The README frames this as the option for when you need explicit control over execution. Steps run in an order you wrote, not an order the model chose.

That distinction matters more than it first appears. Anything with a compliance boundary, a fixed sequence of API calls, or a step that must not be skipped belongs in a workflow. Anything where the path depends on what the model finds belongs in an agent. Mastra lets you put both in one process, which is the main reason to prefer it over a single-paradigm library.

Human-in-the-loop sits across both. The README states that you can suspend an agent or workflow and await user input or approval before resuming, and that Mastra uses storage to remember execution state so you can pause indefinitely and resume where you left off. That storage requirement is the constraint to plan for: suspend and resume is only as durable as the storage backend you configure.

Installing Mastra and running a first agent

The README calls the CLI the recommended way to start. The command below scaffolds a project, and the documentation notes that it also installs Mastra skills for detected coding assistants and initializes Git when appropriate.

npm create mastra@latest

The README also documents a non-interactive form that takes a project name and a provider. The supported provider values listed in that prompt are openai, anthropic, google and xai.

npm create mastra@latest my-mastra-app -- --llm openai

Once the project exists, the README's pre-built prompt enters the directory and starts the dev server through a background process wrapper.

npx bgproc start -n my-mastra-app -w -- npm run dev

What you should see is the dev server coming up and Mastra Studio available at http://localhost:4111. The README describes Studio as the interface for building, testing, and managing agents, workflows, and tools, so that port is where you check whether the scaffold worked before writing any application code.

If you would rather not use the CLI, the README points to the installation guide for a manual install, and to the templates, course and YouTube links for people new to AI agents. The repository also carries an examples/ directory with agent, durable-agents, voice-agent and evals-with-memory entries, which is a faster read than the documentation when you want to see a working shape.

Where Mastra's design puts the burden on you

Suspend and resume is the feature most likely to disappoint if you skim it. The README is explicit that execution state lives in storage and that this is what lets a paused run resume later. It does not describe what happens when the storage backend is unavailable, and the README does not document rollback or a recovery path for a suspended run whose state cannot be read. If your workflow pauses for a human approval that may arrive days later, the durability of that pause is your storage configuration, not a property of the framework.

The agent loop has a similar edge. The README says an agent iterates internally until the model emits a final answer or an optional stopping condition is met. Optional means that if you do not set one, the bound on iteration is whatever the model decides. Cost control in that configuration is your problem.

There is also a plain scope limit. Mastra is TypeScript, and the README's integration story is React, Next.js and Node.js, or a standalone server. Teams on JVM or Python services would be adopting a second runtime to use it, which is a real cost the README does not address.

Finally, the observability and eval features are described in the README as built-in, with links to their documentation sections. The README itself does not state what storage or export format the observability data uses, so that is something to confirm in the docs before you plan a dashboard around it.

Mastra compared with LangChain and LangGraph

The comparison people search for most is Mastra versus LangChain, and the second is Mastra versus LangGraph. The honest difference is language and packaging, not capability.

LangChain's ecosystem is Python-first, with a JavaScript port that has historically trailed the Python release. Mastra is TypeScript-first: the repository is a pnpm workspace of TypeScript packages, the root package.json declares `"type": "module"`, and the build runs through Turbo across packages, server-adapters, integrations, stores, deployers and speech. There is no second language to keep in sync.

The LangGraph comparison is closer to a design difference. LangGraph models agent execution as an explicit graph, and so does Mastra's workflow engine, with `.then()`, `.branch()` and `.parallel()`. The distinction is that Mastra ships the graph engine alongside the agent abstraction, model routing and MCP server authoring in one framework, where LangGraph is the orchestration layer you pair with other libraries. If you already have a working Python agent stack, switching to Mastra buys you TypeScript, not a different execution model.

One more difference worth naming: Mastra can author Model Context Protocol servers that expose agents, tools and other structured resources over the protocol. That is a packaging decision about where your agent lives, and it is not something the comparison with LangChain answers.

Licence split, maintenance and upgrade cost

The repository uses a dual-licence model, and the split is the thing to read before you commit to a feature. The README states that the core framework and the vast majority of the codebase is Apache-2.0, while code in any directory named `ee/` is source-available under the Mastra Enterprise License. Those features require a valid enterprise licence for production use but can be freely used for development and testing. The README gives `packages/core/src/auth/ee/` as an example path and points to LICENSE.md for the full mapping and ee/LICENSE for the terms. This is a description of the licence files, not legal advice; read LICENSE.md yourself before shipping.

On maintenance, the last push to the default branch was on 2026-09-09, and the most recent release in the list is @mastra/[email protected] on the same day, with 1.64.0 on 2026-09-03 and 1.63.0 on 2026-08-26. The repository is not archived. That release cadence means upgrades arrive often, and the root package.json shows the workspace pins dependencies through a pnpm catalog and runs changesets for publishing, so version bumps are a routine part of working in this repo rather than an occasional event.

The practical upgrade cost is that Mastra is a workspace of many packages, not one. The build scripts alone split into build:packages, build:server-adapters, build:integrations, build:combined-stores, build:deployers, build:speech, build:cli and build:server. If you depend on more than @mastra/core, expect to track versions across several of those.

Editorial conclusion

Adopt Mastra if your application is already TypeScript and you want agents, explicit graph workflows, suspend and resume, evals and MCP servers from one package rather than stitching libraries together. Do not adopt it if you need a non-Node runtime, or if the features you want live under packages/core/src/auth/ee/, where production use requires a valid enterprise licence. Verify first that the specific capability you are planning around is not in an ee/ directory, and confirm the published version of @mastra/core you are pinning to before you write the first agent.

Frequently asked questions

Official sources

1. Issues
2. mastra-ai/mastra on GitHub
3. Project website
4. README
5. Releases