What Is Mastra? TypeScript AI Agent Framework

TL;DR

TL;DR: Mastra is an open-source TypeScript framework from the creators of Gatsby that lets you build AI agents with workflow graphs, RAG pipelines, memory, evals, and a local playground for debugging.

Source and Accuracy Notes

• Homepage: mastra.ai
• GitHub: github.com/mastra-ai/mastra (24K+ stars)
• NPM: npm create mastra

What Is Mastra?

Mastra is an open-source JavaScript/TypeScript SDK for building AI-powered applications and agents. It was created by the team behind Gatsby, who later worked on an AI-powered CRM and noticed they were re-implementing the same patterns: agentic workflows, evals, and RAG. Mastra abstracts these patterns into a proper framework.

The core primitives are:

• Workflow graphs — define agent pipelines that can suspend and resume
• Agents — LLM-powered actors with tools and instructions
• Memory — persistent context across agent conversations
• RAG pipelines — retrieval-augmented generation with indexing and retrieval
• Evals — built-in evaluation framework for testing agent quality
• Local playground — visual debugger for iterating on prompts and workflows

Setup Workflow

Prerequisites

• Node.js 18 or higher
• npm or pnpm

Step 1: Create a New Mastra Project

npm create mastra@latest my-agent-project
cd my-agent-project

This scaffolds a new project with TypeScript configuration and example agents.

Step 2: Define Your First Agent

Create a file src/agents/my-agent.ts:

import { Agent } from "@mastra/core";

const myAgent = new Agent({
  name: "my-first-agent",
  instructions: "You are a helpful assistant that can search the web and summarize findings.",
  model: "gpt-4o",
  tools: [], // Add tools here
});

export default myAgent;

Step 3: Add Tools

Tools extend what agents can do. Mastra supports MCP servers as tools:

import { MCPTool } from "@mastra/core";

const webSearchTool = new MCPTool({
  name: "web-search",
  description: "Search the web for current information",
  // MCP server configuration
});

const agent = new Agent({
  name: "research-agent",
  instructions: "You are a research assistant. Use tools to find accurate, up-to-date information.",
  tools: [webSearchTool],
});

Step 4: Create a Workflow

Workflows let agents handle multi-step tasks with branching logic:

import { Workflow } from "@mastra/core";

const researchWorkflow = new Workflow({
  name: "research-pipeline",
  trigger: { input: "topic" },
});

researchWorkflow
  .step("search", async ({ input }) => {
    return await agent.run({ input: `Research: ${input}` });
  })
  .step("summarize", async ({ input }) => {
    return await summarizer.run({ input: input });
  })
  .commit();

export default researchWorkflow;

Step 5: Add Memory

Memory enables agents to retain context across conversations:

import { Memory } from "@mastra/core";

const memory = new Memory({
  // Configure vector store for retrieval
  vectorStore: {
    provider: "pg",
    connectionString: process.env.DATABASE_URL,
  },
});

const agent = new Agent({
  name: "contextual-assistant",
  instructions: "You remember previous conversations and can reference past context.",
  memory,
});

Step 6: Run the Local Playground

Mastra ships with a visual playground for debugging:

npx mastra dev

This starts a local server with a web UI where you can step through agent execution, inspect memory state, and test prompts interactively.

Deeper Analysis

Architecture

Mastra is built on top of Vercel’s AI SDK. Where the AI SDK provides the raw primitives (streaming, tool calls, model routing), Mastra adds the operational layer: workflow orchestration, memory management, evaluation harnesses, and a development UI.

The workflow system uses a graph-based model where each step is a function that receives context and returns a result. Steps can suspend (waiting for user input or external events) and resume with new data.

Memory System

Mastra’s memory is not simple chat history. It uses a vector-backed retrieval system that can:

• Store conversations and facts in a PostgreSQL vector store
• Retrieve relevant context based on semantic similarity
• Summarize old conversations to compress context windows
• Maintain long-term persistent memory across sessions

Eval Framework

Quality assurance for LLM applications is notoriously hard. Mastra includes an eval system that lets you:

• Define test cases with expected inputs and outputs
• Run agents against test suites automatically
• Measure quality scores across different model providers
• Compare prompt versions to catch regressions

MCP Integration

Model Context Protocol (MCP) is a standard for connecting AI models to external tools. Mastra has first-class MCP support, meaning you can plug in any MCP server as a tool for your agents. This includes file systems, databases, web search, and custom APIs.

Practical Evaluation Checklist

• [ ] npm create mastra succeeds and project runs without errors
• [ ] Define a simple agent and verify it responds to basic prompts
• [ ] Add a tool (MCP server or custom function) and verify tool calling works
• [ ] Build a two-step workflow and verify suspend/resume behavior
• [ ] Connect memory and verify context persists across conversations
• [ ] Run evals against your agent and verify quality scores
• [ ] Start the local playground (npx mastra dev) and interact with the visual debugger
• [ ] Deploy to production — check the deployment documentation for your target platform

Security Notes

• API keys: Store model API keys in environment variables, not in source code
• Tool permissions: MCP tools may have broad system access — audit tool permissions before production use
• Memory data: If using persistent memory, ensure the vector store is secured and access-controlled
• Workflow inputs: Sanitize external inputs to workflow triggers to prevent prompt injection

FAQ

Q: How does Mastra compare to LangChain or LlamaIndex?

A: Mastra is more opinionated than LangChain — it provides a specific project structure, built-in evaluation, and a visual debugger rather than a general-purpose toolkit. If you want maximum flexibility and don’t mind building your own scaffolding, LangChain is wider. If you want a framework that handles the operational patterns out of the box, Mastra is more productive.

Q: Can I self-host Mastra?

A: Yes. Mastra is open-source and can be deployed to any Node.js hosting environment. The local playground is development-only, but the agent runtime, workflows, and memory systems run on any platform that supports Node.js.

Q: Does Mastra support other models besides OpenAI?

A: Yes. Mastra supports multiple model providers through the AI SDK, including Anthropic, Google Gemini, Mistral, and local models via Ollama.

Q: Is Mastra production-ready?

A: The framework is actively maintained with 24K+ GitHub stars and a published track record. As with any AI application framework, production readiness depends on your specific implementation — test thoroughly with the eval framework before going live.

Conclusion

Mastra fills a gap in the TypeScript AI tooling landscape: a framework, not just a SDK. The built-in workflow system, memory management, eval harness, and local playground make it faster to go from prototype to production. With MCP integration and support for multiple model providers, it’s a practical choice for teams building agentic applications in TypeScript.

If you’re building AI agents in Node.js/TypeScript and finding yourself re-implementing workflow orchestration and memory management, Mastra is worth a look.

Related reading

Related reading: TypeScript AI agent frameworks, Developer tools, openmonoagent local docker coding agent, and kapso whatsapp api for developers.