Mastra - TypeScript AI Agent Framework Cheatsheet

Mastra - TypeScript AI Agent Framework Cheatsheet

Mastra is an open-source TypeScript framework for AI agents and workflows, built by the team behind Gatsby. Where most agent frameworks are Python-first, Mastra targets the JavaScript/TypeScript ecosystem with full type safety: typed agents with tools and memory, durable workflows expressed as graphs with branching and suspend/resume, RAG primitives, built-in evals, and a local dev playground for iterating on agents in the browser.

Installation

Method	Command
Create a project	npm create mastra@latest
Add to existing	npm install @mastra/core
Dev server	npm run dev (playground at localhost:4111)
Model provider	npm install @ai-sdk/openai (uses Vercel AI SDK)
Verify	open the playground

Defining an Agent

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

export const supportAgent = new Agent({
  name: "support",
  instructions: "You are a concise support agent. Cite docs when possible.",
  model: openai("gpt-4o"),
  tools: { searchDocs },
});

const result = await supportAgent.generate("How do I rotate my API key?");
console.log(result.text);

Method	Does
.generate(input)	Run once and return the result
.stream(input)	Stream tokens/steps
tools	Typed tools the agent may call
memory	Persistent conversation memory

Tools

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

export const searchDocs = createTool({
  id: "search-docs",
  description: "Search the product documentation",
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.object({ results: z.array(z.string()) }),
  execute: async ({ context }) => {
    return { results: await search(context.query) };
  },
});

Zod schemas give end-to-end type safety — the agent’s tool calls are validated and typed on both sides.

Workflows (Durable Graphs)

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

const fetchData = createStep({ id: "fetch", execute: async () => ({ ... }) });
const analyze   = createStep({ id: "analyze", execute: async ({ inputData }) => ({ ... }) });

export const pipeline = createWorkflow({ id: "pipeline" })
  .then(fetchData)
  .then(analyze)
  .commit();

Feature	Purpose
.then()	Sequential steps
.branch()	Conditional paths
.parallel()	Concurrent steps
.dowhile() / .foreach()	Loops over data
Suspend/resume	Pause for human input, resume later
Durable execution	Survives restarts

Memory

Type	Use
Conversation history	Recent turns in context
Semantic recall	Vector search over past messages
Working memory	Persistent facts about the user
Storage adapters	LibSQL, Postgres, Upstash

RAG Primitives

Piece	Provides
Document chunking	Split docs with configurable strategies
Embeddings	Via the AI SDK providers
Vector stores	pgvector, Pinecone, Qdrant, Chroma
Retrieval tool	Wire retrieval into an agent as a tool

Evals & Observability

Capability	Note
Built-in evals	Answer relevancy, faithfulness, toxicity, bias
Custom scorers	Define your own metrics
Tracing	OpenTelemetry-compatible traces
Playground	Inspect agent runs, tools, and memory locally

Deployment

Target	Note
Node server	mastra build produces a deployable server
Vercel / Cloudflare / Netlify	Official deployers
Serverless	Workflows designed for stateless hosts

Mastra vs Other Agent Frameworks

Aspect	Mastra	LangGraph	CrewAI
Language	TypeScript	Python	Python
Workflows	Durable graph + suspend/resume	Stateful graph	Role-based crews
Type safety	Strong (Zod end-to-end)	Python typing	Python typing
Best for	TS/JS teams, web apps	Complex stateful agents	Multi-agent role play

The TypeScript counterpart to LangGraph; compare with CrewAI and AutoGen for Python.

Resources

• Official Website
• GitHub Repository
• Documentation