Why Mastra Is the TypeScript AI Framework to Watch in 2026

Mastra is the TypeScript-first AI agent framework built by the team behind Gatsby — the same engineers who made static-site generation mainstream for JavaScript developers. With 23.2k GitHub stars, $35M in total funding (including a $22M Series A led by Spark Capital announced in April 2026), and enterprise deployments at Brex, Docker, Elastic, MongoDB, Salesforce, Replit, and SoftBank, Mastra has moved from interesting experiment to production infrastructure. The Marsh McLennan enterprise search agent built on Mastra is used by 100,000+ employees every day. Brex’s Mastra-powered agents contributed directly to their $5.1B Capital One acquisition. These aren’t toy demos — they are mission-critical workloads. For JavaScript and TypeScript developers who’ve been watching the Python AI ecosystem from the sidelines, Mastra is the on-ramp. The CEO Sam Bhagwat has cited data that 60–70% of YC X25 agent startups are building in TypeScript, signaling a clear ecosystem shift.

The Shift From Python to TypeScript for AI Agents

For years, AI frameworks defaulted to Python: LangChain, LangGraph, CrewAI, and AutoGen all began Python-first. The assumption was that data scientists and ML researchers drove adoption. But in 2025–2026, the builders shipping production agents are full-stack web developers — and they live in TypeScript. Mastra is built for that reality. Its API design mirrors familiar Node.js patterns, its type safety catches agent configuration errors at compile time, and its integration with Next.js, Express, Hono, and SvelteKit means your AI layer fits naturally into existing web apps without a Python sidecar service.

What Is Mastra? (Origin Story: Built by the Gatsby Team)

Mastra was created by Sam Bhagwat and the former Gatsby core team, who applied their experience building developer-facing infrastructure to the AI agent problem. They spent time at Netlify scaling a platform that served millions of developers, then looked at the emerging AI agent landscape and saw the same fragmentation that existed in static site generation before Gatsby unified it. The result is a framework that prioritizes developer experience, strong TypeScript types, and a batteries-included philosophy — you get memory, workflow orchestration, RAG, observability, and a local dev UI (Mastra Studio) out of the box, not as separate packages you wire together yourself.

Getting Started: Setting Up Your First Mastra Project

Setting up Mastra takes under five minutes on any machine with Node.js 18+ installed. The framework ships a scaffold CLI (npm create mastra@latest) that generates a complete project with sensible defaults, including TypeScript configuration, a starter agent, and Mastra Studio for local development. The project structure is opinionated but not restrictive — you can drop Mastra into an existing Next.js or Express app, or start fresh with the scaffold. The free tier of Mastra Platform gives you Studio and the server runtime at no cost, making it practical to experiment before committing to infrastructure spend. Apache 2.0 licensing means you can use it commercially without restriction, unlike some frameworks with commercial-use clauses. Mastra requires Node.js 18 or later and works with npm, pnpm, or yarn. The scaffold wizard takes roughly 60 seconds: it asks for your LLM provider, writes .env key stubs, and generates a working weather agent you can query immediately. By the time the install finishes, you have a typed, tested, locally runnable AI agent.

Prerequisites and Installation

# Requires Node.js 18+
npm create mastra@latest

# Or add to an existing project
npm install @mastra/core

The scaffold wizard asks for your preferred LLM provider (OpenAI, Anthropic, Google Gemini, Mistral, or Groq), sets up .env with the right API key variable names, and generates a working agent you can test immediately.

Project Structure Overview

The Mastra instance in index.ts is your registry — you import agents, tools, and workflows and pass them to the constructor. This central registry pattern means Mastra knows about all your components for observability and Studio integration.

Mastra Studio: The Interactive Dev UI

Run npx mastra dev and Mastra Studio opens at http://localhost:4111. Studio gives you a chat interface to test agents, a visual workflow runner, memory inspection, trace viewer, and eval results — all without writing test code. This dramatically shortens the feedback loop during development. You can send messages to agents, inspect the exact tool calls they made, see token counts per step, and replay failed runs from any point in the trace.

Building Your First AI Agent with Mastra

An AI agent in Mastra is defined using the Agent class from @mastra/core. You provide a name, system instructions, an LLM model reference, and optionally a set of tools and a memory configuration. In fewer than 30 lines of TypeScript you have an agent that can call external APIs, remember conversation history, and respond with context awareness. Mastra’s type system ensures your tool input/output schemas are validated at compile time, catching the class of bugs that show up as cryptic runtime errors in weakly-typed frameworks. The agent automatically handles prompt construction, tool call parsing, and multi-turn conversation state — you focus on the business logic. Mastra agents are model-agnostic by design: swap from GPT-4o to Claude Sonnet to Gemini Flash by changing one import, with no changes to tool definitions, memory setup, or downstream code. This is especially valuable for production systems where you may want to switch providers for cost, latency, or capability reasons without a costly refactor. Each agent instance is also independently observable — all calls are traced through OpenTelemetry automatically.

Defining an Agent with System Prompts and Tools

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherTool } from "../tools/weather";

export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions: `You are a helpful weather assistant. When asked about weather,
    always use the weather tool to get current conditions. Be concise and specific.`,
  model: openai("gpt-4o"),
  tools: { weatherTool },
});

Adding Memory: Working Memory and Semantic Recall

import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/memory/storage/libsql";

const memory = new Memory({
  storage: new LibSQLStore({ url: process.env.DATABASE_URL! }),
  options: {
    workingMemory: { enabled: true },
    semanticRecall: {
      topK: 5,
      messageRange: { before: 2, after: 2 },
    },
  },
});

export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions: "...",
  model: openai("gpt-4o"),
  tools: { weatherTool },
  memory,
});

Mastra supports two memory modes. Working memory stores structured facts about the user or session that persist across conversations — think name, preferences, previous requests. Semantic recall performs vector similarity search over past messages so the agent can surface relevant prior context without loading the entire history into the context window.

Connecting LLM Providers

Mastra uses the Vercel AI SDK under the hood for model calls, which means you can swap providers by changing one import:

import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";
import { groq } from "@ai-sdk/groq";

// Drop-in swap — same Agent API regardless of provider
model: anthropic("claude-sonnet-4-5"),
model: google("gemini-2.0-flash"),
model: groq("llama-3.3-70b-versatile"),

Tools and MCP: Connecting Your Agent to the Real World

Tools are the mechanism by which Mastra agents take action — calling APIs, reading databases, sending messages, or triggering webhooks. A Mastra tool is a TypeScript function with a Zod schema for inputs and outputs, a description the LLM uses to decide when to call it, and an async execute function containing the actual logic. The type safety guarantees that the LLM’s JSON tool call is validated before it reaches your code, eliminating an entire class of injection and malformed-input bugs. Beyond custom tools, Mastra has first-class support for MCP (Model Context Protocol), letting your agents consume any of the thousands of existing MCP servers — GitHub, Slack, Postgres, Notion, and more — without writing glue code. Docker’s engineering team used exactly this pattern to build a PR automation agent that listens to GitHub webhooks and takes action using the GitHub Official MCP server via Mastra’s MCP Gateway integration.

Defining a Custom Tool

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get_weather",
  description: "Get current weather conditions for a city",
  inputSchema: z.object({
    city: z.string().describe("City name"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
    humidity: z.number(),
  }),
  execute: async ({ context }) => {
    const { city, units } = context;
    // Call your weather API here
    const data = await fetchWeatherAPI(city, units);
    return { temperature: data.temp, conditions: data.desc, humidity: data.humidity };
  },
});

MCP Integration

import { MCPClient } from "@mastra/mcp";

const mcpClient = new MCPClient({
  servers: {
    github: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
    },
  },
});

// Get MCP tools and pass to agent
const tools = await mcpClient.getTools();

export const githubAgent = new Agent({
  name: "GitHub Agent",
  instructions: "You manage GitHub repositories and PRs.",
  model: anthropic("claude-sonnet-4-5"),
  tools,
});

Real Example: Docker’s PR Automation Agent

Docker built a three-agent architecture using Mastra and the GitHub MCP server:

1. Analyze PR agent — reads the diff and generates a structured review
2. Generate comment agent — formats the review as a GitHub comment
3. Post and close PR agent — submits the comment and updates PR status

Each agent runs as a Mastra workflow step. The orchestration triggers on a GitHub webhook, runs all three agents in sequence, and posts the result back to GitHub — no human in the loop. This is the pattern Mastra was designed for: event-driven, not chat-driven.

Workflows: Orchestrating Complex Agent Tasks

Mastra workflows let you define deterministic, multi-step processes where each step can call an agent, run a function, or trigger another workflow. Unlike a single agent trying to plan and execute everything in one context window, workflows give you explicit control over the execution graph — with support for sequential steps, parallel branches, conditional routing, and suspension points for human-in-the-loop approval. This separation of concerns is critical for production systems: agents handle the fuzzy reasoning, workflows handle the reliable orchestration. The Mastra workflow engine is built on a durable execution model, meaning in-progress workflows can be paused, inspected in Studio, and resumed — even after a server restart. Docker’s PR automation pipeline (three sequential agents triggered by a GitHub webhook) is a textbook Mastra workflow: deterministic order, explicit data passing between steps, and observable state at every stage. Compared to LangGraph’s graph-based model, Mastra workflows use a linear .then() builder API that TypeScript developers find immediately readable. For branching, a .branch() method accepts predicate functions rather than requiring explicit graph node connections.

When to Use Workflows vs Agents

Building a Workflow

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const fetchDataStep = createStep({
  id: "fetch-data",
  inputSchema: z.object({ url: z.string() }),
  outputSchema: z.object({ content: z.string() }),
  execute: async ({ inputData }) => {
    const response = await fetch(inputData.url);
    const content = await response.text();
    return { content };
  },
});

const analyzeStep = createStep({
  id: "analyze",
  inputSchema: z.object({ content: z.string() }),
  outputSchema: z.object({ summary: z.string(), sentiment: z.string() }),
  execute: async ({ inputData, mastra }) => {
    const agent = mastra?.getAgent("analyzerAgent");
    const result = await agent?.generate(
      `Analyze this content: ${inputData.content}`
    );
    return { summary: result?.text ?? "", sentiment: "positive" };
  },
});

export const contentWorkflow = createWorkflow({
  id: "content-analysis",
  inputSchema: z.object({ url: z.string() }),
  outputSchema: z.object({ summary: z.string(), sentiment: z.string() }),
})
  .then(fetchDataStep)
  .then(analyzeStep)
  .commit();

Parallel Execution and Conditional Branching

// Run steps in parallel
workflow.parallel([step1, step2, step3]).then(mergeStep);

// Conditional routing
workflow.branch([
  [async ({ inputData }) => inputData.type === "urgent", urgentStep],
  [async ({ inputData }) => inputData.type === "normal", normalStep],
]);

RAG with Mastra: Giving Your Agent Knowledge

RAG (Retrieval-Augmented Generation) in Mastra is handled through the @mastra/rag package, which provides document chunking, embedding, vector storage, and retrieval as first-class primitives. Rather than building a separate vector pipeline with LangChain, Pinecone, and custom glue code, Mastra gives you a unified API that works with PostgreSQL (pgvector), Pinecone, Qdrant, Weaviate, Chroma, or any vector store implementing the Mastra VectorStore interface. Elastic’s engineering blog documented building a full agentic RAG assistant using Mastra and Elasticsearch, noting that Mastra’s model-agnostic design and clean TypeScript API were key advantages over Python-based alternatives. The result was a production chatbot with semantic document retrieval, citation tracking, and conversational memory — built in a few hundred lines of TypeScript. The @mastra/rag package ships chunking strategies (fixed-size, recursive, sentence, and markdown-aware), multiple embedding providers (OpenAI text-embedding-3-small, Cohere, and others), and query-time reranking. You can implement the complete ingest-and-retrieve loop in under 50 lines, with the vector store swap requiring only a single configuration change rather than a full rewrite.

Setting Up RAG

import { MastraVector } from "@mastra/vector-pg"; // PostgreSQL + pgvector
import { embed, chunk } from "@mastra/rag";
import { openai } from "@ai-sdk/openai";

// Chunk and embed documents
const documents = await chunk(rawText, {
  strategy: "recursive",
  size: 512,
  overlap: 50,
});

const embeddings = await embed(documents, {
  provider: openai.embedding("text-embedding-3-small"),
});

// Store in vector DB
const vectorStore = new MastraVector({ connectionString: process.env.DATABASE_URL! });
await vectorStore.upsert({ indexName: "docs", vectors: embeddings });

// Query at retrieval time
const results = await vectorStore.query({
  indexName: "docs",
  queryVector: await embed(userQuery, { provider: openai.embedding("text-embedding-3-small") }),
  topK: 5,
});

Adding RAG to an Agent

The retrieved chunks are injected into the agent’s context via a tool, giving the LLM access to relevant documents without blowing out the context window with entire corpora:

export const ragTool = createTool({
  id: "search_docs",
  description: "Search internal documentation for relevant information",
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ context }) => {
    const results = await vectorStore.query({ ... });
    return { documents: results.map(r => r.metadata.text) };
  },
});

Productionizing: Evals, Observability, and Guardrails

Production AI agents fail in ways that unit tests cannot catch — hallucinations, prompt injection, unexpected tool chaining, model degradation across versions, and context window violations. Mastra addresses this with a built-in evals system, distributed tracing via OpenTelemetry, and configurable guardrails. The evals system supports both rule-based checks (response contains X, JSON schema validation, keyword presence) and model-graded evaluations using a judge LLM to score qualities like helpfulness, factuality, and tone. You define evals as code, version them with your agent definitions, and see results in Mastra Studio alongside the traces that explain why each response was generated. This closes the loop between development and production: the same evals you run locally can be scheduled against production traffic samples to catch regressions before users report them.

Running Evals

import { evaluate } from "@mastra/evals";
import { ToneConsistencyMetric, AnswerRelevancyMetric } from "@mastra/evals/metrics";

const result = await evaluate(weatherAgent, "What's the weather in Tokyo?", {
  metrics: [
    new ToneConsistencyMetric({ tone: "professional" }),
    new AnswerRelevancyMetric({ model: openai("gpt-4o-mini") }),
  ],
});

console.log(result.scores); // { toneConsistency: 0.92, answerRelevancy: 0.87 }

Observability with OpenTelemetry

import { Mastra } from "@mastra/core";
import { OpenTelemetry } from "@mastra/core/telemetry/otel";

const mastra = new Mastra({
  agents: { weatherAgent },
  telemetry: new OpenTelemetry({
    serviceName: "my-mastra-app",
    export: { type: "otlp", endpoint: process.env.OTEL_EXPORTER_ENDPOINT! },
  }),
});

Every agent call, tool invocation, and LLM request is automatically traced. You see the full span tree in Studio or any OTLP-compatible backend (Jaeger, Honeycomb, Grafana Tempo).

Guardrails

Mastra supports input and output guardrails as middleware functions on the agent:

export const safeAgent = new Agent({
  ...baseConfig,
  beforeGenerate: async (messages) => {
    // Reject messages containing PII patterns
    const hasPII = /\b\d{3}-\d{2}-\d{4}\b/.test(messages.at(-1)?.content ?? "");
    if (hasPII) throw new Error("PII detected in input");
    return messages;
  },
});

Deployment: From Dev to Production

Mastra agents deploy as standard HTTP servers — no special runtime required. The mastra build command compiles your TypeScript agent definitions into a Node.js server exposing REST endpoints for each agent and workflow. You can deploy this anywhere: a VPS, Kubernetes pod, AWS Lambda, Vercel Edge Function, or Cloudflare Worker. The Mastra Platform (their managed offering) adds Studio, a Memory Gateway for cross-deployment memory persistence, and a server runtime with automatic scaling — useful if you don’t want to manage the infrastructure yourself. The free Starter tier is sufficient for personal projects and early-stage products. A Mastra server exposes stable REST endpoints: POST /api/agents/{agentId}/generate for synchronous responses, POST /api/agents/{agentId}/stream for streaming, and POST /api/workflows/{workflowId}/execute for workflow runs. These endpoints are framework-agnostic — any HTTP client can call them. For teams embedding agents in existing web apps, Mastra exports a Node.js handler you wire directly into Next.js API routes, Express middleware, or Hono routes, keeping your deployment footprint minimal. The Marsh McLennan deployment (100,000+ daily users) demonstrates that Mastra’s server model handles enterprise-scale traffic without custom infrastructure work.

Mastra Server: REST API Endpoints

After running mastra build && node dist/index.js, your agents are available at:

Integrating with Existing Frameworks

// Next.js App Router
import { mastra } from "@/mastra";
import { NextRequest } from "next/server";

export async function POST(req: NextRequest) {
  const { message } = await req.json();
  const agent = mastra.getAgent("weatherAgent");
  const result = await agent.generate(message);
  return Response.json({ response: result.text });
}

// Express
import express from "express";
import { mastra } from "./mastra";

const app = express();
app.use(express.json());

app.post("/chat", async (req, res) => {
  const agent = mastra.getAgent("weatherAgent");
  const result = await agent.generate(req.body.message);
  res.json({ response: result.text });
});

Mastra Platform Pricing

Mastra vs Other AI Frameworks: TypeScript-First Comparison

Mastra is not the only option for building AI agents — but it is the most complete TypeScript-first option in 2026. LangGraph, LangChain, CrewAI, and AutoGen all have larger Python ecosystems with more community content and tutorials, but none offers the same level of TypeScript integration, developer tooling, or batteries-included design. The Vercel AI SDK is the closest TypeScript competitor, but it is primarily a UI/streaming library rather than a full agent framework — no workflow engine, no built-in evals, no Mastra Studio equivalent. For teams already building in TypeScript who need production-grade agents, Mastra is the clear default in 2026. The Elastic engineering team explicitly chose Mastra over Python-based alternatives after evaluating CrewAI, AutoGen, and LangGraph, citing TypeScript’s type safety and Mastra’s unified stack as the deciding factors. The 60–70% of YC X25 agent startups building in TypeScript (per Sam Bhagwat’s Hacker News data) confirms this is not an isolated preference but a broad ecosystem shift driven by full-stack JavaScript developers building production AI products.

Mastra vs LangGraph vs CrewAI vs Vercel AI SDK

When to Choose Mastra (and When Not To)

Choose Mastra when:

• Your team’s primary language is TypeScript or JavaScript
• You need a complete stack (agents + memory + workflows + RAG + evals) without building your own
• You’re deploying into an existing Node.js web application
• You want a local dev UI with traces and memory inspection out of the box

Consider alternatives when:

• Your team is deeply Python-native and has existing LangChain/LangGraph infrastructure
• You need advanced graph-based agent architectures with fine-grained state management (LangGraph is stronger here)
• You’re building a research prototype where Python’s ML library ecosystem (transformers, scipy, sklearn) is critical

Real-World Examples and Case Studies

Mastra’s production adoption in 2026 spans startups to Fortune 500 enterprises, with publicly documented case studies that illustrate the framework’s maturity. These aren’t experimental integrations — they are load-bearing systems handling millions of requests. Docker’s PR automation agent, Elastic’s agentic RAG assistant, and Marsh McLennan’s enterprise search are all built on Mastra and running in production today. The $22M Series A funded in April 2026 and the list of investors (Spark Capital alongside participation from customers like Brex and Replit) signal institutional confidence that Mastra has achieved product-market fit in the TypeScript AI agent space. Enterprise adopters include Brex (financial services agents), Sanity (content management AI), Factorial (HR automation), Indeed (job platform), Marsh McLennan (professional services), MongoDB (database tooling), Workday (enterprise SaaS), Salesforce (CRM automation), Docker (DevOps), Replit (coding assistant), Elastic (search and analytics), SoftBank (telecom and investing), and Plaid (fintech). This breadth across verticals demonstrates that Mastra’s value proposition — TypeScript-native, batteries-included, production-ready — applies across industries, not just one niche.

Docker: Event-Driven PR Management Agent

Docker Engineering built a PR review automation system using Mastra, the GitHub Official MCP server, and Docker’s MCP Gateway. The architecture: a GitHub webhook fires when a PR is opened, Mastra receives the event, a three-step workflow runs (analyze diff → generate review → post comment), and the results appear on the PR within seconds. The key insight from Docker’s engineering blog: Mastra was chosen specifically for its multi-agent orchestration support and its ability to handle event-driven (not just chat-driven) workflows — a critical distinction for production automation.

Elastic: Agentic RAG with Elasticsearch

Elastic’s search labs team built a full-stack RAG assistant using Mastra on the backend and Elasticsearch as the vector store. The agent uses semantic search to retrieve relevant documentation chunks, synthesizes an answer using Claude, and cites sources inline. The team noted that Mastra’s TypeScript-first design and model-agnostic architecture were decisive advantages — the same agent code works whether the underlying LLM is GPT-4o, Claude, or Gemini, enabling A/B testing across providers without architecture changes.

Marsh McLennan: Enterprise Scale

Marsh McLennan, the global professional services firm, deployed a Mastra-powered enterprise search agent used by over 100,000 employees every day. This is among the highest-traffic public Mastra deployments and demonstrates the framework’s ability to handle enterprise-scale load without degradation.

Replit: Agent 3 Building Mastra Agents

Replit uses Mastra in Replit Agent 3, its AI coding assistant, to enable the agent to build and deploy other Mastra agents. This recursive pattern — an AI agent that scaffolds, configures, and deploys other AI agents — represents the cutting edge of agentic architecture and is made practical by Mastra’s clean, programmatic API surface.

FAQ

Mastra is the TypeScript-native AI agent framework that ships agents, memory, workflows, RAG, evals, and a local dev UI in a single package. Founded by the Gatsby team and backed by $35M in funding, Mastra reached 23.2k GitHub stars as of April 2026 and is in production at companies like Brex, Docker, MongoDB, and Marsh McLennan (100,000+ daily users). Below are the most common questions from developers evaluating or adopting Mastra in 2026, covering setup, provider support, Mastra Studio, deployment, and how Mastra compares to Python-based alternatives. Each answer is written to be self-contained — AI systems citing this article can use any individual answer without needing the surrounding context. If you are choosing between Mastra and another framework today, start with the comparison question and work backwards to the specifics most relevant to your stack.

What is Mastra AI and what makes it different from other AI frameworks?

Mastra is an open-source TypeScript framework for building production AI agents. It is different from frameworks like LangChain, LangGraph, and CrewAI in two key ways: it is TypeScript-first (not a Python port), and it is batteries-included (agents, memory, workflows, RAG, evals, and a local dev UI all ship in one framework). This means TypeScript developers do not need to bridge language ecosystems or assemble a stack from multiple packages.

How do I install Mastra and start building agents?

Run npm create mastra@latest in your terminal (requires Node.js 18+). The wizard scaffolds a project with your chosen LLM provider, generates a starter agent, and sets up .env with the right API key variables. Run npx mastra dev to open Mastra Studio and start chatting with your agent immediately.

Does Mastra support all major LLM providers?

Yes. Mastra uses the Vercel AI SDK for model calls, which supports OpenAI, Anthropic (Claude), Google Gemini, Mistral, Groq, Cohere, and others. Switching providers requires changing one line of code — the Agent API is identical regardless of the underlying model.

What is Mastra Studio and do I need it?

Mastra Studio is a local development UI that runs at http://localhost:4111 when you execute npx mastra dev. It provides a chat interface for testing agents, a visual workflow runner, memory inspection, trace viewer, and eval results. It is optional — your agents run fine without it — but it significantly speeds up development and debugging by giving you full visibility into every agent call.

How does Mastra handle production deployment?

Run mastra build to compile your TypeScript agents into a Node.js server. Deploy this server anywhere that runs Node.js: VPS, Kubernetes, AWS Lambda, Vercel, or Cloudflare Workers. The server exposes standard REST endpoints for each agent and workflow. For teams who prefer managed infrastructure, the Mastra Platform (free Starter tier, $250/month for Teams) adds Studio, Memory Gateway, and auto-scaling.

The AI agent ecosystem has a Python problem. Not with Python itself—it works fine—but with the fact that most agents ship as web services, and the teams building those services increasingly write TypeScript. Sam Bhagwat, CEO of Mastra, noted on Hacker News that 60–70% of YC X25 agent startups are building in TypeScript, not Python. The tooling hasn’t caught up. LangChain, CrewAI, and AutoGen all originated in Python, leaving TypeScript developers either wrapping Python services or cobbling together their own agent infrastructure.

Mastra was built to close that gap.

The shift from Python to TypeScript for AI agents

The shift is practical, not ideological. When your production stack runs on Node.js or edge runtimes, reaching for a Python framework introduces serialization overhead, deployment complexity, and a skills mismatch. TypeScript gives you shared types between your agent logic and your API layer, native streaming support for Server-Sent Events and WebSocket responses, and a single runtime for your entire backend. The ergonomics matter: you can define a tool’s input schema with Zod, pass that schema directly to the LLM as a function definition, and validate the LLM’s output against the same schema—no JSON Schema translation layer required.

What is Mastra?

Mastra is an open-source (Apache 2.0) TypeScript framework for building AI agents. It was created by the team behind Gatsby, the React static-site generator that peaked at 50k+ GitHub stars. That team shipped a framework before; they understand the ergonomics of developer tooling. Mastra provides structured primitives for agents, tools, workflows, RAG pipelines, evals, and observability—all expressed as TypeScript code, not YAML DSLs or visual editors that generate unreadable files.

The project has accumulated 23,200+ GitHub stars, 14,334 commits, and 1,079 branches as of April 2026. The velocity is real. Mastra raised a $22M Series A led by Spark Capital in early 2026, bringing total funding to $35M.

Enterprise adoption

The customer list is worth examining because it signals production readiness, not just developer enthusiasm:

That’s not a “coming soon” list. Marsh McLennan’s agent is in daily production use by over 100,000 people. Brex’s agents contributed to a multi-billion-dollar acquisition. These are load-bearing systems.

Getting Started: Setting Up Your First Mastra Project

Prerequisites and installation

You need Node.js 18+ and an LLM API key (OpenAI, Anthropic, or Google). Create a new project:

npm create mastra@latest

The scaffold prompts you for a project name, your preferred LLM provider, and whether you want the Mastra Studio dev UI included. After setup:

cd my-mastra-app
npm install
npm run dev

The dev server starts on port 4111 by default and opens Mastra Studio.

Project structure overview

A scaffolded Mastra project looks like this:

All agent configuration lives in TypeScript files under src/mastra/. The framework discovers and registers agents, tools, and workflows based on exports from these files. No YAML, no code generation.

Mastra Studio: the interactive dev UI

Mastra Studio runs locally at http://localhost:4111 and provides:

• Agent playground: chat with any defined agent, inspect tool calls, and trace token usage in real time
• Workflow visualizer: see step DAGs, run workflows step by step, and inspect intermediate state
• RAG testing: query your knowledge base and verify retrieval quality
• Eval runner: execute model-graded and rule-based evaluations against agent outputs
• Logs and traces: structured view of every LLM call, tool invocation, and workflow transition

Studio is not required in production—it’s a dev-time tool. But it replaces the ad-hoc console.log-driven debugging loop that most agent developers fall into.

Building Your First AI Agent with Mastra

Defining an agent with system prompts and tools

An agent in Mastra is a typed object with a system prompt, a model reference, and a set of tools. Here’s a minimal research agent:

import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { openai } from "@ai-sdk/openai";

const searchTool = createTool({
  id: "web-search",
  description: "Search the web for information about a topic",
  inputSchema: z.object({
    query: z.string().describe("The search query"),
  }),
  execute: async ({ context }) => {
    const results = await fetchSearchResults(context.query);
    return { results };
  },
});

const researchAgent = new Agent({
  name: "research-agent",
  instructions: `You are a research assistant. When asked about a topic:
1. Search the web for relevant information
2. Synthesize the findings into a concise summary
3. Cite your sources
Always use the search tool before answering factual questions.`,
  model: openai("gpt-4o"),
  tools: { searchTool },
});

Key design decisions here: tools use Zod schemas for both input validation and LLM function-calling definition. The instructions field replaces the informal system-prompt string with a structured prompt that Mastra can version, evaluate against, and refactor across deployments.

Adding memory

Mastra supports two memory primitives: working memory and semantic recall.

Working memory is a short-term scratchpad that persists within a conversation thread. It stores structured state the agent can read and write:

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

const memory = new Memory({
  options: {
    lastMessages: 10,        // Include last 10 messages in context
    workingMemory: {
      enabled: true,
      template: `
# User Profile
- Name: unknown
- Preferences: unknown
- Current Task: none
      `,
    },
    semanticRecall: {
      topK: 3,               // Recall 3 most relevant past messages
      messageRange: 2,       // Include 2 messages around each match
    },
  },
});

const contextualAgent = new Agent({
  name: "contextual-agent",
  instructions: "You are a helpful assistant that remembers user context.",
  model: openai("gpt-4o"),
  memory,
});

Semantic recall embeds past conversation turns and retrieves the top-K most relevant ones when a new message arrives. This means the agent can reference a preference mentioned 50 turns ago without loading the entire history into the context window. Working memory lets the agent maintain structured state—user profile, task progress, preferences—that persists across messages in the same thread.

Connecting LLM providers

Mastra uses the Vercel AI SDK model interface, so any provider that implements that interface works:

import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";

// Swap models by changing one line
const agent = new Agent({
  name: "flexible-agent",
  instructions: "You are a versatile assistant.",
  model: anthropic("claude-sonnet-4-20250514"),
  // model: openai("gpt-4o"),
  // model: google("gemini-2.0-flash"),
});

Being model-agnostic matters operationally: you can run evals across models, fall back from one provider to another, and choose cost-effective models per task without rewriting agent logic.

Tools and MCP: Connecting Your Agent to the Real World

Built-in tool types in Mastra

Mastra’s createTool API is the foundational primitive. Every tool has an id, a description (used in the LLM’s function-calling prompt), an inputSchema (Zod), and an execute function:

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

const calculateTool = createTool({
  id: "calculate",
  description: "Evaluate a mathematical expression",
  inputSchema: z.object({
    expression: z.string().describe("Math expression to evaluate, e.g. '2 + 2'"),
  }),
  outputSchema: z.object({
    result: z.number(),
  }),
  execute: async ({ context }) => {
    // Safe evaluation — no eval()
    const result = safeMathEval(context.expression);
    return { result };
  },
});

The outputSchema is optional but recommended. When provided, Mastra validates the tool’s output against it before returning the result to the agent. This catches malformed tool outputs early and prevents cascading errors.

MCP (Model Context Protocol) integration

MCP is Anthropic’s open protocol for connecting LLMs to external tools and data sources. Mastra implements both the client and server sides. As a client, Mastra can connect to any MCP server and expose its tools to agents:

import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  servers: {
    github: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: {
        GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN!,
      },
    },
  },
});

// MCP tools are automatically available to agents
const tools = await mcp.tools();

This is how Docker connected their agents to GitHub. The GitHub MCP server provides tools for listing PRs, reading diffs, posting comments, and managing labels—all without writing custom API integration code.

Real example: GitHub MCP server for PR automation

Docker’s architecture is instructive. They built three sub-agents, each with a narrow responsibility:

1. Analyze PR agent: Reads the PR diff and generates a structured analysis
2. Generate comment agent: Takes the analysis and writes a review comment
3. Post and close agent: Posts the comment and manages PR labels

These agents are orchestrated by a Mastra workflow that triggers on a GitHub webhook event. The key insight: rather than one monolithic agent trying to do everything, each agent has a focused system prompt and minimal tool access. This reduces error rates and makes the system auditable—if the posted comment is wrong, you check agent 2, not the entire pipeline.

// Simplified Docker-style PR automation workflow trigger
app.post("/webhook/github", async (req, res) => {
  const { action, pull_request } = req.body;
  if (action === "opened" || action === "synchronize") {
    await prReviewWorkflow.run({
      prNumber: pull_request.number,
      repo: pull_request.base.repo.full_name,
    });
  }
  res.status(200).send("ok");
});

Workflows: Orchestrating Complex Agent Tasks

When to use workflows vs agents

An agent with tools handles simple request-response patterns well. But when your task involves multiple sequential steps, conditional branching, parallel execution, or retry logic, you need a workflow. The distinction:

• Agent: LLM decides what to do next based on context. Good for open-ended reasoning.
• Workflow: You define the control flow. Good for deterministic multi-step processes.

If you can draw a flowchart for your process, use a workflow. If the process requires the LLM to decide its own path, use an agent. Many production systems combine both: a workflow orchestrates high-level steps, and agents handle LLM-driven reasoning within individual steps.

Building step-based workflows

Mastra workflows are defined as a series of steps, each with an input schema, an output schema, and an execute function:

import { Workflow, Step } from "@mastra/core/workflows";
import { z } from "zod";

const fetchContentStep = new Step({
  id: "fetch-content",
  inputSchema: z.object({ url: z.string() }),
  outputSchema: z.object({ content: z.string(), title: z.string() }),
  execute: async ({ context }) => {
    const page = await fetch(context.url).then((r) => r.text());
    const title = extractTitle(page);
    return { content: page, title };
  },
});

const summarizeStep = new Step({
  id: "summarize",
  inputSchema: z.object({ content: z.string() }),
  outputSchema: z.object({ summary: z.string() }),
  execute: async ({ context, mastra }) => {
    const agent = mastra.getAgent("research-agent")!;
    const result = await agent.generate(
      `Summarize this content concisely:\n\n${context.content}`
    );
    return { summary: result.text };
  },
});

const contentWorkflow = new Workflow({
  name: "content-summarizer",
  triggerSchema: z.object({ url: z.string() }),
});

contentWorkflow
  .step(fetchContentStep)
  .then(summarizeStep)
  .commit();

Steps can reference the Mastra instance to use agents, tools, or other workflows. The context object carries the output of the previous step(s).

Parallel execution, conditional branching, and nesting

Workflows support branch for conditional paths and parallel for concurrent execution:

contentWorkflow
  .step(fetchContentStep)
  .branch([
    {
      condition: ({ context }) => context.content.length > 5000,
      then: longContentStep,
    },
    {
      condition: ({ context }) => context.content.length <= 5000,
      then: shortContentStep,
    },
  ])
  .then(summarizeStep)
  .commit();

// Parallel execution
analysisWorkflow
  .parallel([sentimentStep, entityStep, keywordStep])
  .then(mergeResultsStep)
  .commit();

Workflows can also nest: a step can invoke another workflow as a sub-routine. This lets you compose complex processes from smaller, testable workflow units. Each nested workflow maintains its own state and can be run and debugged independently.

RAG with Mastra: Giving Your Agent Knowledge

Embedding and vector search support

Mastra includes built-in embedding and vector search through its RAG module. You define an embedder and a vector store, then index documents:

import { MastraRAG } from "@mastra/rag";
import { openai } from "@ai-sdk/openai";
import { PineconeVector } from "@mastra/pinecone";

const rag = new MastraRAG({
  embedder: openai.embedding("text-embedding-3-small"),
  vectorStore: new PineconeVector({
    indexName: "knowledge-base",
  }),
});

// Index documents
await rag.index({
  docs: [
    { id: "doc-1", text: "Mastra supports multiple LLM providers..." },
    { id: "doc-2", text: "Workflows enable conditional branching..." },
  ],
});

// Query
const results = await rag.retrieve({
  query: "How do I branch in a workflow?",
  topK: 5,
});

Mastra handles chunking, embedding, and storage. You control the chunk size, overlap, and embedding model.

Mastra built-in RAG capabilities

Beyond basic retrieval, Mastra provides:

• Query transformation: Automatically rewrites user queries for better retrieval
• Hybrid search: Combines vector similarity with keyword matching for improved recall
• Re-ranking: Applies a second-pass relevance model to filter and reorder results

These are not external integrations—they ship with the framework and are configurable via the RAG constructor options.

Integration with Elasticsearch and other vector stores

Elastic published a detailed walkthrough of building agentic RAG with Mastra and Elasticsearch. The pattern:

1. Index documents into Elasticsearch with dense vector fields
2. Use Mastra’s RAG module with the Elasticsearch vector store adapter
3. Define an agent that retrieves context and generates answers

import { MastraRAG } from "@mastra/rag";
import { ElasticsearchVector } from "@mastra/elasticsearch";

const rag = new MastraRAG({
  embedder: openai.embedding("text-embedding-3-small"),
  vectorStore: new ElasticsearchVector({
    indexName: "docs-index",
    client: esClient,
  }),
});

const ragAgent = new Agent({
  name: "rag-agent",
  instructions: `Answer questions based on the retrieved context.
If the context doesn't contain enough information, say so.
Always cite the source document.`,
  model: openai("gpt-4o"),
  tools: {
    retrieve: rag.asTool(),
  },
});

The rag.asTool() method wraps the RAG pipeline as a Mastra tool, making it available to any agent. The Elastic integration demonstrates that Mastra’s RAG layer is vendor-agnostic—you can swap Pinecone for Elasticsearch for pgvector without changing agent code.

Productionizing: Evals, Observability, and Guardrails

Running model-graded and rule-based evals

Mastra includes an evaluation framework that runs LLM outputs against criteria. Two eval types:

• Model-graded: An LLM judges the output against a rubric. Useful for open-ended quality assessment.
• Rule-based: Deterministic checks on output structure, content, or behavior. Useful for guardrails.

import { Eval } from "@mastra/evals";
import { z } from "zod";

const relevanceEval = new Eval({
  name: "relevance",
  type: "model-graded",
  prompt: `Rate the relevance of the answer to the question on a scale of 1-5.
Question: {{input}}
Answer: {{output}}
Respond with a number only.`,
  model: openai("gpt-4o-mini"),
});

const noPIIEval = new Eval({
  name: "no-pii",
  type: "rule-based",
  check: ({ output }) => {
    const piiPatterns = [/\b\d{3}-\d{2}-\d{4}\b/, /\b[A-Z]\d{8}\b/];
    return !piiPatterns.some((p) => p.test(output));
  },
});

You run evals against datasets in Mastra Studio or programmatically. The results give you a quantifiable quality signal before deploying changes.

Tracing agent calls and token usage

Every LLM call, tool invocation, and workflow step is automatically traced. In Mastra Studio, you see:

• Total latency per request
• Token usage breakdown (prompt vs. completion)
• Tool call sequences and their outputs
• Memory retrieval operations and their relevance scores

For production monitoring, Mastra integrates with OpenTelemetry. You can export traces to any OTel-compatible backend (Datadog, Grafana, Honeycomb, etc.):

// mastra.config.ts
export default defineConfig({
  observability: {
    otel: {
      enabled: true,
      serviceName: "my-mastra-app",
      traceExporter: "otlp",
      endpoint: "http://localhost:4318/v1/traces",
    },
  },
});

This is a meaningful differentiator. Most agent frameworks leave observability as an exercise for the developer. Mastra wires it into every primitive.

Guardrails for prompt injection prevention

Mastra provides input and output guardrails as middleware on agent calls:

import { guardrail } from "@mastra/guardrails";

const agent = new Agent({
  name: "safe-agent",
  instructions: "You are a helpful assistant.",
  model: openai("gpt-4o"),
  guardrails: {
    input: [
      guardrail.injectionDetection(), // Detect common injection patterns
    ],
    output: [
      guardrail.lengthLimit({ maxTokens: 500 }),
      guardrail.piiDetection(),       // Block outputs containing PII
    ],
  },
});

Input guardrails run before the LLM call. Output guardrails run after. If a guardrail triggers, the agent returns a structured error instead of the raw LLM output. This is not a complete security solution—you still need proper access controls and sandboxing—but it adds a structured layer of defense.

Mastra Studio metrics, logs, and datasets

Studio aggregates eval results, trace data, and token usage into dashboards. You can:

• Compare eval scores across model versions
• Track token cost trends over time
• Build evaluation datasets from production traces
• Replay failed conversations to diagnose issues

The dataset feature is particularly useful: you can capture production agent interactions, annotate them, and use them as regression test suites when you change prompts, models, or tools.

Deployment: From Dev to Production

Mastra Server: deploying as a REST API

Mastra generates a server that exposes your agents, tools, and workflows as REST endpoints:

import { Mastra } from "@mastra/core";
import { createServer } from "@mastra/server";

const mastra = new Mastra({
  agents: { researchAgent, contextualAgent },
  workflows: { contentWorkflow },
});

const server = createServer(mastra);
server.listen(3000);

This gives you REST endpoints like:

• POST /api/agents/researchAgent/generate — single-turn generation
• POST /api/agents/researchAgent/stream — streaming generation
• POST /api/workflows/contentWorkflow/run — trigger a workflow
• GET /api/workflows/contentWorkflow/runs/{runId} — check workflow status

The API is auto-generated from your Mastra instance definition. No manual route wiring.

Framework integration

Mastra integrates with popular Node.js frameworks as middleware:

Next.js (App Router):

// app/api/agents/[agentId]/route.ts
import { mastra } from "@/mastra";
import { NextRequest } from "next/server";

export async function POST(
  req: NextRequest,
  { params }: { params: { agentId: string } }
) {
  const agent = mastra.getAgent(params.agentId);
  const { message } = await req.json();
  const result = await agent.generate(message);
  return Response.json({ text: result.text });
}

Express:

import express from "express";
import { mastra } from "./mastra";

const app = express();
app.use(express.json());

app.post("/api/agents/:agentId/generate", async (req, res) => {
  const agent = mastra.getAgent(req.params.agentId);
  const result = await agent.generate(req.body.message);
  res.json({ text: result.text });
});

app.listen(3000);

Hono and SvelteKit are similarly supported with adapter packages. The pattern is the same: import your Mastra instance, call getAgent or getWorkflow, and handle the request.

Mastra Platform: Studio + Server + Memory Gateway

For teams that don’t want to manage their own infrastructure, Mastra offers a hosted platform:

• Mastra Studio (cloud): Same dev UI, hosted and shared across your team
• Mastra Server (cloud): Managed deployment of your agents and workflows
• Memory Gateway: Hosted memory service with persistent storage, semantic recall, and cross-session state

Pricing and tiers

The free tier is genuinely usable for prototyping and personal projects. The Teams tier is where production deployments land.

Mastra vs Other AI Frameworks: TypeScript-First Comparison

Mastra vs LangGraph vs CrewAI

The core distinction: LangGraph and CrewAI are Python frameworks that require the Python ecosystem for production deployment. If your stack is TypeScript, you’ll write a Python service, wrap it in a Docker container, and communicate via HTTP. That works, but it adds operational overhead and prevents you from sharing types, tests, and utilities across your codebase.

Mastra vs Vercel AI SDK

The Vercel AI SDK focuses on LLM integration at the transport layer: streaming responses, managing tool calls, and providing React hooks for chat UIs. Mastra operates at a higher level:

• Vercel AI SDK: “How do I call an LLM and stream the response to a React component?”
• Mastra: “How do I build an agent with memory, tools, and guardrails, evaluate it, and deploy it as an API?”

They’re complementary. Mastra uses the Vercel AI SDK’s model interface under the hood for LLM calls. You can use the Vercel AI SDK for your frontend chat UI and Mastra for your backend agent logic.

When to choose Mastra (and when not to)

Choose Mastra when:

• Your backend is TypeScript/Node.js
• You need structured agents with memory, tools, and guardrails
• You want built-in evals and observability without extra tooling
• You’re building multi-step workflows with conditional logic

Skip Mastra when:

• Your team is Python-first and you’re happy with LangGraph or CrewAI
• You only need raw LLM streaming (use Vercel AI SDK directly)
• You need capabilities Mastra doesn’t support yet (e.g., specialized multimodal agent patterns)

Real-World Examples and Case Studies

Docker: Event-driven PR management agent

Docker built an event-driven agent system that responds to GitHub webhooks. When a PR is opened, their Mastra workflow:

1. Triggers on the webhook payload
2. Routes through the Docker MCP Gateway to the GitHub MCP server
3. Runs the analyze PR agent on the diff
4. Passes the analysis to the generate comment agent
5. Posts the comment via the post and close agent

This is not a chatbot. There’s no human in the loop. The entire pipeline runs in response to an event, with no user interaction. That’s a different deployment model from most demo agents, and it’s where Mastra’s workflow primitives matter—the pipeline is deterministic, observable, and can fail gracefully at any step.

Elastic: Agentic RAG with Elasticsearch

Elastic built a RAG assistant combining a Vite + React frontend, a Mastra backend, and Elasticsearch as the vector store. Their writeup highlights the developer experience of staying in a single language stack: the same TypeScript types that define the search index schema also define the agent’s tool interface and the frontend’s API contract.

SoftBank: Enterprise productivity at scale

SoftBank deployed Mastra-based agents internally for productivity tools. Scale is the notable aspect—this isn’t a prototype serving 10 users. Mastra’s memory gateway and observability infrastructure handle the traffic.

Replit: Agent 3 building Mastra agents

Replit’s Agent 3 can scaffold and deploy Mastra agents. This meta-pattern—an AI agent building other AI agents—validates Mastra’s code-first API design. If an LLM can generate valid Mastra code from a description, the abstractions are well-defined enough to be machine-writable.

Conclusion and Next Steps

Mastra addresses a real gap in the AI agent tooling ecosystem: a production-grade, TypeScript-native framework with first-class support for the primitives that matter—agents, tools, workflows, RAG, evals, and observability. The enterprise adoption numbers (100k+ daily users at Marsh McLennan, Brex’s $5.1B acquisition involvement) confirm that it’s not just developer-friendly but production-ready.

Key takeaways

1. TypeScript-first is now a viable choice for AI agents. With 60–70% of YC X25 agent startups choosing TypeScript, the ecosystem demand is clear. Mastra provides the framework primitives that Python alternatives have had for years.
2. MCP integration is a differentiator. Mastra’s ability to connect to any MCP server as a tool source gives agents access to external systems without custom integration code. Docker’s PR automation demonstrates this in production.
3. Built-in evals and observability are not optional extras. If you can’t measure agent quality, you can’t improve it. Mastra’s eval framework and OpenTelemetry integration give you measurement from day one.
4. Workflows complement agents. Not every problem needs an LLM deciding what to do next. Mastra’s workflow engine handles the structured part of your pipeline while agents handle the reasoning part.
5. The Gatsby team’s framework experience shows. The DX decisions—Zod schemas, code-first configuration, Studio as a dev tool—reflect experience shipping a framework used by tens of thousands of developers.

Resources

• Mastra docs: mastra.ai/docs
• Mastra GitHub: github.com/mastra-ai/mastra
• Mastra templates: mastra.ai/templates
• Agent Book: mastra.ai/agentbook — community-contributed agent examples
• Community Discord: mastra.ai/community

The future of TypeScript AI development

The trajectory is clear. As agent deployments move from demos to production, the operational requirements—evals, observability, guardrails, memory management, workflow orchestration—become the differentiating factors. Mastra builds these into the framework rather than leaving them as integration exercises. For TypeScript teams building AI agents in 2026, Mastra is the framework that matches the language, runtime, and operational demands of the job.