Mastra Documentation — TypeScript AI Agent Framework
by Mastra
Build agents in TypeScript without dropping into Python — agents, workflows, memory and MCP in one framework.
Overview
Mastra is the TypeScript answer to a Python-dominated agent ecosystem, built by the team behind Gatsby and part of Y Combinator's W25 batch. The repository carries roughly 27,000 stars, and version 1.0 landed in January 2026 — the Show HN thread reached 213 points and 70 comments, with the maintainers reporting around 300,000 weekly npm downloads at the time. The docs are organised around primitives rather than tutorials. An agent is defined by an id, a name, instructions, a model in provider/model form, and optional tools created with createTool(); model routing reaches over 40 providers through a single interface. Workflows are graph-based and composed with .then(), .branch() and .parallel(), with suspend and resume so a human approval step can persist state across a process restart. Other documented areas include memory and conversation history, RAG, structured output as typed objects, streaming via .stream(), processors that intercept and transform messages, guardrails, rubric scorers for self-correction, voice, and Slack, Discord and Telegram channels. MCP is supported in both directions — consuming external servers and exposing your own agents as one. Getting started is npm create mastra@latest, which scaffolds an agent harness plus Mastra Studio, a local dashboard on port 4111. Node.js 22.18 or later is required. The core is Apache-2.0, with enterprise directories under a separate source-available licence.
At a Glance
- Topic
- Frameworks
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- Reference documentation, self-paced — about 3-4 hours to work through agents, tools, memory and workflows
- Provider
- Mastra
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Define a TypeScript agent with instructions, a routed model, and typed tools built via createTool
- ✓Compose graph-based workflows using .then, .branch and .parallel for deterministic control flow
- ✓Suspend a workflow for human approval and resume it later with persisted state intact
- ✓Give agents conversation memory and retrieval-augmented context over your own documents
- ✓Return typed structured objects instead of free text, and stream tokens back to a UI
- ✓Consume MCP servers as tools and expose your own Mastra agents as an MCP server
- ✓Add guardrails, processors and rubric scorers, then deploy into Next.js, Node or a standalone server
Highlights
- •First-class TypeScript rather than a port — the whole stack stays in one language for web teams
- •Model routing across 40+ providers behind one interface, so swapping models is a string change
- •Suspend and resume with persisted state makes human-in-the-loop a framework primitive, not a workaround
- •Mastra Studio gives a local dashboard on port 4111 for inspecting agent runs during development
- •Reached 1.0 in January 2026 with a well-received Show HN — the API surface has stopped churning
Who It’s For
Best For
- ✓Full-stack and frontend teams who want agents without adding a Python service
- ✓Next.js or Node developers integrating LLM features into an existing product
- ✓Engineers who need durable, human-in-the-loop workflows rather than a single-shot agent loop
Prerequisites
- •Solid TypeScript and Node.js — version 22.18 or later is required
- •Familiarity with LLM API basics such as prompts, tool calling and streaming responses
- •An API key for at least one supported model provider to run any of the examples
FAQ
What is Mastra Documentation — TypeScript AI Agent Framework?
The official documentation for Mastra, an open-source TypeScript framework for building AI agents and workflows. It covers agents with tools and memory, graph-based workflows with suspend and resume, model routing across 40-plus providers, RAG, evals, MCP on both the client and server side, and deployment into Next.js, Node or a standalone server. Written for developers whose stack is already TypeScript.
Is Mastra Documentation — TypeScript AI Agent Framework free?
Mastra Documentation — TypeScript AI Agent Framework is free to access.
What level is Mastra Documentation — TypeScript AI Agent Framework for?
Mastra Documentation — TypeScript AI Agent Framework is aimed at a intermediate audience. Recommended background: Solid TypeScript and Node.js — version 22.18 or later is required, Familiarity with LLM API basics such as prompts, tool calling and streaming responses, An API key for at least one supported model provider to run any of the examples.
How long does Mastra Documentation — TypeScript AI Agent Framework take?
Expect roughly Reference documentation, self-paced — about 3-4 hours to work through agents, tools, memory and workflows. Most learners work through it at their own pace.
What will I learn from Mastra Documentation — TypeScript AI Agent Framework?
You'll learn: Define a TypeScript agent with instructions, a routed model, and typed tools built via createTool; Compose graph-based workflows using .then, .branch and .parallel for deterministic control flow; Suspend a workflow for human approval and resume it later with persisted state intact; Give agents conversation memory and retrieval-augmented context over your own documents; Return typed structured objects instead of free text, and stream tokens back to a UI; Consume MCP servers as tools and expose your own Mastra agents as an MCP server; Add guardrails, processors and rubric scorers, then deploy into Next.js, Node or a standalone server.
Topics
Sources
This page was written from 3 sources, 2 on domains other than mastra.ai.