====== 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:

  * **Agents** -- Run conversational tool-calling loops where the LLM decides which functions to invoke
  * **Tools** -- Typed functions with Zod schemas that agents can call, providing structured input/output
  * **Workflows** -- Graph-based deterministic pipelines that control execution order, branching, and parallelism

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

  * **RAG** -- Document processing, embedding generation, vector storage, and context retrieval
  * **Memory** -- Persistent agent memory across conversations via PostgreSQL, LibSQL, or Upstash
  * **MCP Support** -- Model Context Protocol integration for tool discovery and sharing
  * **Evals** -- Model-graded, rule-based, and statistical evaluation methods
  * **Voice** -- Native speech-to-text and text-to-speech support

===== Code Example =====

<code python>
// 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();
</code>

===== System Flow =====

<code>
%%{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)]
</code>

===== Key Features =====

  * **TypeScript-Native** -- Full type safety with Zod schemas for tools and workflows
  * **Graph Workflows** -- Deterministic multi-step pipelines with branching and parallelism
  * **MCP Integration** -- Model Context Protocol for standardized tool sharing
  * **Developer Studio** -- Local playground for testing and visualizing agents
  * **Multi-Provider** -- OpenAI, Anthropic, Google Gemini via unified interface
  * **Deployment** -- Next.js, Express, Hono, serverless, or Mastra Cloud

===== References =====

  * [[https://github.com/mastra-ai/mastra|Mastra GitHub Repository]]
  * [[https://mastra.ai|Official Website]]
  * [[https://mastra.ai/docs|Documentation]]
  * [[https://mastra.ai/blog/choosing-a-js-agent-framework|Framework Comparison Blog Post]]

===== See Also =====

  * [[vanna|Vanna]] -- AI text-to-SQL using RAG
  * [[xagent|XAgent]] -- Autonomous agent with hierarchical planning
  * [[ragas|RAGAS]] -- Evaluate agent and RAG pipeline quality