Table of Contents

Mastra: TypeScript-First AI Agent Framework

Mastra is an open-source TypeScript framework for building AI agents, workflows, and tools with built-in memory, MCP support, and observability. Created by the team behind Gatsby.js and backed by $13 million in Y Combinator seed funding, Mastra has grown to over 22,000 GitHub stars and 300,000 weekly npm downloads. It provides a complete toolkit for going from prototype to production with AI agents in the JavaScript/TypeScript ecosystem.

Unlike Python-centric agent frameworks (LangGraph, CrewAI, AutoGen), Mastra is designed for web developers who need real-time UIs, streaming responses, authentication flows, and modern deployment pipelines – all in TypeScript with full type safety.

Architecture

Mastra is organized around three fundamental primitives:

The framework acts as a central orchestrator coordinating agents, workflows, storage, and logging into a unified system. Additional built-in capabilities include:

Code Example

// Agent definition with tools
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
 
// Define a typed tool
const searchTool = {
  name: "search_docs",
  description: "Search internal documentation",
  schema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    const results = await vectorStore.search(query, { topK: 5 });
    return results.map(r => r.text).join("
");
  },
};
 
// Create an agent with tools and memory
const researchAgent = new Agent({
  name: "Research Assistant",
  instructions: "You help users find information in our documentation.",
  model: openai("gpt-4o"),
  tools: [searchTool],
});
 
// Create a multi-step workflow
import { Step, Workflow } from "@mastra/core/workflows";
 
const researchStep = new Step({
  id: "research",
  execute: async ({ context }) => {
    const result = await researchAgent.generate(context.triggerData.query);
    return { research: result.text };
  },
});
 
const summarizeStep = new Step({
  id: "summarize",
  execute: async ({ context }) => {
    const data = context.getStepResult("research");
    const result = await summaryAgent.generate(`Summarize: ${data.research}`);
    return { summary: result.text };
  },
});
 
const workflow = new Workflow({
  name: "research-pipeline",
  triggerSchema: z.object({ query: z.string() }),
});
 
workflow.step(researchStep).then(summarizeStep).commit();

System Flow

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#6C5CE7"}}}%%
graph TD
    A[User Request] --> B[Mastra Orchestrator]
    B --> C{Route}
    C -->|Agent| D[Agent Loop]
    C -->|Workflow| E[Workflow Engine]
    D --> F[LLM Provider]
    F --> G{Tool Call?}
    G -->|Yes| H[Execute Tool]
    H --> F
    G -->|No| I[Response]
    E --> J[Step 1: Research Agent]
    J --> K[Step 2: Writer Agent]
    K --> L[Step 3: Review Agent]
    L --> M[Final Output]
    D --> N[Memory Store]
    E --> N
    N --> O[(PostgreSQL / LibSQL)]

Key Features

References

See Also