Mastra

Overview

Mastra is an open-source TypeScript framework for building AI applications: agents that use tools and remember conversations, workflows that run steps in a controlled order, retrieval over your own documents, and evaluations that score the results. It is designed for teams that already build web products in JavaScript or TypeScript and want to add agents without switching to Python.

Mastra brings the main agent building blocks into one package with one set of conventions. It runs on Node.js and related runtimes, plugs into web frameworks, and can be deployed to common cloud and serverless platforms. It is model-agnostic: it uses the Vercel AI SDK's model interface, so the same code can call models from many providers.

An everyday comparison is a fitted kitchen bought as one set. You could buy a cooker from one shop, cupboards from another and a sink from a third, then spend weeks making them fit. Or you can buy a kitchen where the units, worktop and plumbing are designed together. Mastra is the fitted kitchen for TypeScript agent apps: agents, workflows, memory, retrieval and evals that already fit each other.

What it is

Mastra is a set of npm packages with a core library, a command-line tool and a local development interface. The core framework is open source under the Apache 2.0 licence. The company behind it also offers a separate paid cloud platform for hosting and observability.

Where it came from

Mastra was built by members of the team that created Gatsby, the React-based website framework. The company took part in Y Combinator's Winter 2025 batch. The founders' view was that most agent tooling targeted Python, while a large share of the developers building product features worked in TypeScript.

The framework grew quickly through 2025 as an open-source project, adding workflows, memory, RAG, evals, MCP support and a local development interface. Mastra 1.0 was released in January 2026, marking a stable API for the core framework.

How it works

Step 1: Define tools

A tool has an ID, a description, an input schema and an execute function. Schemas are written with Zod, a TypeScript validation library, so the tool's arguments are typed and checked. A tool might look up stock levels, send a message or query a database.

Step 2: Define an agent

An agent has a name, instructions, a model and a set of tools. You can attach memory. When the agent runs, it sends the conversation and tool schemas to the model, executes any tool calls, and loops until the model gives an answer. You can ask for plain text, a stream, or a structured object that matches a schema. See structured outputs.

Step 3: Add memory

Memory is stored per conversation thread and per user. It has three layers:

• Conversation history: recent messages in the thread.
• Working memory: a small, persistent record of key facts, such as the user's name or preferences, that the agent updates.
• Semantic recall: older messages retrieved by meaning when they are relevant to the current question.

Storage backends include local databases and hosted databases. See agent memory for the general idea.

Step 4: Build workflows

A workflow is built from steps. Each step has typed input and output schemas and an execute function. You chain them: .then() runs steps in sequence, .branch() picks a path by condition, and .parallel() runs several steps at once. Loops repeat a step while a condition holds. Steps can call agents or tools, or be plain code.

A step can suspend the workflow, for example to wait for a person's approval, and the workflow resumes later from the same point with the new input. This is how human-in-the-loop gates are built.

Step 5: Retrieve documents

The RAG helpers chunk documents, create embeddings, store them in a vector database and retrieve relevant chunks. An agent can be given a retrieval tool, so it searches when it needs facts. See agentic RAG.

Step 6: Develop, evaluate and deploy

Running the development command starts a local server and web interface, where you can chat with agents, run workflows step by step and inspect traces. Scorers measure output quality on test data. When ready, you deploy the Mastra server to your chosen platform or embed agents in an existing web app.

Key concepts and terms

A worked example

This scenario is illustrative. An online furniture shop adds a delivery assistant to its Next.js website.

1. The team defines three tools: getOrder(orderId), getDeliverySlots(postcode) and rescheduleDelivery(orderId, slotId), each with a Zod schema.
2. A "delivery agent" gets the first two tools and memory per customer thread. Working memory stores the customer's postcode once they give it.
3. Rescheduling runs as a workflow, not a free agent action. Step one checks the order status. Step two offers slots. Step three suspends and waits for the customer to confirm a slot in the chat. Step four calls rescheduleDelivery.
4. A branch sends orders worth more than 2,000 euros to a staff member for approval before the final step.
5. The team writes 60 test conversations and a scorer that checks whether the agent asked for a postcode only when it did not already have one. The first run passes 51 of 60. They improve the instructions and reach 58.

Using a workflow for the change itself keeps the risky action predictable, while the agent handles the conversation.

Strengths and limitations

Strengths:

• Native TypeScript, so web teams can use their existing language, tooling and deployment.
• Agents, workflows, memory, RAG and evals in one consistent framework.
• Typed tools and steps through Zod.
• Workflows with suspend and resume for long or approval-based processes.
• Model-agnostic through the AI SDK, with MCP support.
• Local development interface for fast iteration.

Limitations:

• Smaller ecosystem of examples and integrations than the main Python frameworks.
• Many machine learning libraries live in Python, so some data work still needs a Python service.
• A fast-moving project, so examples from early versions may be outdated.
• Memory and RAG quality depend on the storage and embedding choices you make.
• Hosted observability is a separate commercial product.

How it compares with alternatives

Practical guidance and best practices

1. Use workflows, not free agents, for anything that changes data or costs money.
2. Write clear tool descriptions; the model chooses tools from them.
3. Keep Zod schemas tight, with enums for fixed choices.
4. Use working memory for a few stable facts and semantic recall for long histories.
5. Suspend workflows for approvals rather than letting agents ask and act in one step.
6. Build a small test set and scorers before launch, and re-run them after changes; see evals.
7. Trace every run and review failures weekly.
8. Pin package versions and read release notes before upgrading.

Common mistakes

• Letting an agent call a payment or booking tool directly with no workflow or approval.
• Storing everything in working memory until it becomes a cluttered note.
• Treating RAG as plug-and-play without testing chunk size and retrieval quality.
• Running heavy data processing in the web server process.
• Skipping evals because the demo looked good.

Frequently asked questions

What is Mastra?

Mastra is an open-source TypeScript framework for building AI agents, workflows, memory, retrieval and evaluations, aimed at JavaScript and TypeScript teams.

Who makes Mastra?

It is built by a company founded by members of the team behind Gatsby, the React website framework. The company was part of Y Combinator's Winter 2025 batch.

Does Mastra work with any model?

It is model-agnostic. It uses the Vercel AI SDK's model interface, so it can call models from many providers, including local ones.

How is Mastra different from the Vercel AI SDK?

The AI SDK focuses on calling models and streaming to user interfaces. Mastra builds on it and adds agents with memory, typed workflows, RAG helpers, evals and a development interface.

Can Mastra pause a workflow for a human?

Yes. A workflow step can suspend execution and the workflow resumes later from that step when new input, such as an approval, arrives.

Is Mastra free?

The core framework is open source under Apache 2.0. A separate cloud platform for hosting and observability is a paid product.

Glossary

• Agent: a model with tools and memory.
• Workflow: a graph of typed steps.
• Step: a unit of work with typed input and output.
• Suspend: pause a workflow and save its state.
• Thread: a single conversation.
• Working memory: a short, persistent fact record.
• Semantic recall: meaning-based retrieval of past messages.
• Scorer: a quality measure for outputs.
• Zod: a TypeScript schema and validation library.

Summary

Mastra is an open-source TypeScript framework that gives web teams agents, typed workflows, layered memory, retrieval helpers and evaluations in one consistent package. It was built by members of the Gatsby team and reached 1.0 in January 2026. Its strength is fitting naturally into JavaScript products; its trade-off is a younger ecosystem than the Python frameworks. Put risky actions in workflows with approvals, keep schemas tight and test with scorers before launch.

Related

It belongs to Frameworks in my stack, under Agentic AI. Others in the same group: