Mastra: Agents in TypeScript
Table of contents
- Key takeaways
- What is Mastra?
- How do agents, tools and workflows relate?
- How does it integrate memory and RAG?
- What does a minimal agent in TypeScript look like?
- Mastra or a Python framework?
- Frequently asked questions
- Is Mastra free and open source?
- Which models can I use with Mastra?
- Do I need to know React or Gatsby to use Mastra?
- Conclusion
- Sources
Almost every serious agent framework lives in Python, yet your web app is probably written in TypeScript: Mastra lets you build the agent in the same language as the rest of the product. It is an open-source framework that gathers agents, tools, workflows, memory and RAG into a single package, designed to run on Node.js and at the edge. In this guide you will see what Mastra is, how its pieces relate, how to write a minimal agent in TypeScript, and when to pick it over the Python frameworks. The same explanation is available in Spanish.
Key takeaways
- Mastra is a TypeScript framework for building AI agents and AI applications; it bundles agents, tools, workflows, memory, RAG and evals into a single package.
- It was built by the team behind Gatsby, went through Y Combinator’s W25 batch and closed a 13 million dollar seed round with more than 120 investors; in April 2026 it added a 22 million dollar Series A, for 35 million dollars raised in total.
- It reached version 1.0 in January 2026; the latest release is @mastra/core 1.51.0 (15 July 2026), with about 26,200 GitHub stars and over 300,000 weekly npm downloads.
- It connects to over 40 model providers through one interface, using the
provider/modelformat (for exampleopenai/gpt-5.5oranthropic/claude-sonnet-4-6). - It requires Node.js 22.18.0 or later and installs with
npm create mastra@latest; the core is Apache 2.0.
What is Mastra?
Mastra is an open-source framework written in TypeScript for building AI agents and applications. Its documentation describes it as "a TypeScript framework that gives you everything you need to prototype fast and ship with confidence". The core idea is to gather in a single package the primitives you would otherwise wire together by hand: agents, tools, workflows, memory, document retrieval (RAG) and evals.
Its origin explains a lot of its approach. It is built by the team that created Gatsby (the React-based static-site generator that helped popularize the JAMstack approach), and it came out of Y Combinator’s W25 batch, the Winter 2025 cohort. Months later it closed a 13 million dollar seed round backed by more than 120 investors, including Y Combinator itself, Paul Graham and Guillermo Rauch, the founder of Vercel; in April 2026 it added a 22 million dollar Series A led by Spark Capital, bringing total funding to 35 million dollars. The stable 1.0 release, meanwhile, landed in January 2026.
The traction matches the pitch: the mastra-ai/mastra repository sits near 26,200 stars by mid-2026, the package passes 300,000 weekly npm downloads, and the latest published version is @mastra/core 1.51.0, from 15 July 2026. The core ships under the Apache 2.0 license; only the enterprise features, kept in a separate directory, use a commercial license.
How do agents, tools and workflows relate?
Mastra separates two ways to orchestrate work, and choosing well between them is the most important design decision.
An agent decides on its own: it receives instructions, a model and a set of tools, and at each step the model chooses whether to answer or to call a tool. It is the right pattern when the path is not fixed in advance. A tool is a typed function you create with createTool, with a Zod[1] (the TypeScript schema-validation library) inputSchema that validates the arguments before running it, just like the typed structured output of Pydantic AI in the Python world.
A workflow, by contrast, is a graph of steps you define when you need explicit control of the flow. They chain with a fluent syntax (.then(), .branch(), .parallel()) and are deterministic: they always follow the path you wrote. The rule of thumb is simple: use an agent when you want the model to decide, and a workflow when the order of steps must be fixed and auditable.
How does it integrate memory and RAG?
An agent without memory forgets everything between messages. Mastra ships a built-in memory system that keeps the recent conversation history (working memory) and long-term memories it retrieves by relevance, much like what we describe in memory in AI agents. It connects to a store (LibSQL, a SQLite fork built for edge and serverless deployments; Postgres; or a vector database, say) and attaches to the agent without you orchestrating the reads and writes.
RAG (retrieval-augmented generation) follows the same "batteries included" principle: Mastra offers components to chunk documents, generate embeddings and query a vector database, so the agent answers grounded in your own documents. In July 2026 the project also added Tool Hooks, hooks that let you observe and control every tool call the agent makes, handy for auditing or blocking dangerous actions before they run.
What does a minimal agent in TypeScript look like?
First, create the project or add Mastra to an existing one. The official scaffolding sets up the full structure; the manual install is enough if you already have a Node project:
npm create mastra@latest
npm install @mastra/core zod
A minimal agent is two pieces: a typed tool and the agent that uses it. The tool declares its input schema with Zod, and the agent receives instructions, a model and the set of tools. You run it with agent.generate (full answer) or agent.stream (in chunks):
import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
const weather = createTool({
id: "get-weather",
description: "Returns the weather for a city",
inputSchema: z.object({ city: z.string() }),
execute: async ({ context }) => {
return { text: `It is 22 degrees and clear in ${context.city}.` };
},
});
export const agent = new Agent({
id: "weather-agent",
name: "Weather Agent",
instructions: "You help with the weather. Answer clearly and concisely.",
model: "openai/gpt-5.5",
tools: { weather },
});
const response = await agent.generate("What is the weather in Madrid?");
console.log(response.text);
The model field uses the provider/model format, so switching from OpenAI to Anthropic or to an open model is a matter of rewriting that string. Mastra routes the request to the right provider without you touching the rest of the code.
Mastra or a Python framework?
Most mature agent frameworks are Python: LangChain (the pioneering library for chaining prompts, tools and memory), the OpenAI Agents SDK or Agno. Python dominates in research and data pipelines, and has the richest machine-learning library. Mastra does not compete there: its bet is that many AI applications are, at bottom, web applications, and those already live in TypeScript.
Choosing Mastra has three concrete advantages. You write the agent in the same language as your frontend and Node backend, with no separate Python service to maintain. You use TypeScript’s type system end to end, with Zod validating inputs and outputs. And you deploy where you already deploy JavaScript: Node, containers or edge functions on Vercel or Cloudflare. Against a framework like Microsoft’s Semantic Kernel, which also targets several languages, Mastra is TypeScript-native rather than a port.
| Criterion | Mastra (TypeScript) | Python frameworks |
|---|---|---|
| Language | TypeScript, same as the web | Python, separate service |
| Deployment | Node, container or edge | Python server or container |
| ML ecosystem | More limited | The richest |
| Typing | Static out of the box (Zod) | Optional (Pydantic) |
The rule of thumb: if your product is already TypeScript, Mastra spares you a language switch just to add an agent; if you live in Python’s data ecosystem, stay there.
Frequently asked questions
Is Mastra free and open source?
Yes. Mastra’s core ships under the Apache 2.0 license and you can run it on your own infrastructure with no license cost. Only a set of enterprise features, kept in a separate /ee/ directory, is governed by a commercial license. To build and deploy agents with the @mastra/core package you need no paid plan: you only pay, where applicable, the provider of the model you use.
Which models can I use with Mastra?
More than 40 providers through a single routing interface. You name the model with the provider/model format, such as openai/gpt-5.5, anthropic/claude-sonnet-4-6 or google/gemini-2.5-flash, and Mastra directs the request to the right provider. Switching models means rewriting that string, without touching the agent logic, which makes it easy to prototype with a powerful model and then move part of the work to a cheaper one.
Do I need to know React or Gatsby to use Mastra?
No. Although it is built by the team that created Gatsby, Mastra is a standalone backend framework that only needs Node.js 22.18.0 or later and TypeScript. It works equally well with an Express or Hono backend, with Next.js or with a plain Node script. The Gatsby background shows in the quality of the tooling and docs, not in a dependency on React.
Conclusion
Mastra fills a clear gap: it is the framework that brings agents, tools, workflows, memory and RAG together for anyone building in TypeScript who does not want to stand up a separate Python service. With a stable 1.0 release, Y Combinator backing and a community of more than 26,000 stars, it is a serious bet for web-native AI applications. The natural next step is to spin up the project with npm create mastra@latest, write the minimal agent in this guide and, when you want to compare approaches, look at the OpenAI Agents SDK on the Python side.
Sources: [1] Mastra, official documentation[2], [2] mastra-ai/mastra repository on GitHub[3], [3] Mastra on Y Combinator[4], [4] @mastra/core package on npm[5], [5] Mastra’s Series A announcement[6].
