How to Use Mastra

Mastra is a TypeScript-native AI framework for agents, workflows, and evals, from the team behind Gatsby.

Mastra brings the LangChain-style primitives — agents, tools, memory, RAG, workflows — to idiomatic TypeScript with a strong focus on DX. It ships a local dev playground, built-in tracing, and a workflow engine with branching and retries that feels closer to a real orchestrator than a pile of callbacks. It deploys to Node, Vercel, Cloudflare Workers, or as a standalone server.

What it is

Mastra is an Elastic-2.0 licensed open-source project maintained by the Mastra team (many ex-Gatsby engineers). It is built on top of the Vercel AI SDK for model access, so any provider that SDK supports — OpenAI, Anthropic, Google, Groq, Ollama — is available. TypeScript-first, Zod-powered schemas throughout.

Install

npm create mastra@latest
# or add to an existing project
npm install @mastra/core @ai-sdk/openai zod

First run

Define an agent and call it — the playground at localhost:4111 gives you a chat UI for free:

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

export const assistant = new Agent({
  name: "assistant",
  instructions: "You are a concise coding helper.",
  model: openai("gpt-4o-mini"),
})

const { text } = await assistant.generate("Explain useEffect in 2 lines.")
console.log(text)

Everyday workflows

• Compose createWorkflow().step().then().branch() to build durable multi-step pipelines with typed inputs.
• Attach tools defined with createTool and a Zod schema — Mastra handles the JSON-schema conversion.
• Add evals (mastra/evals) to score agent outputs against golden datasets in CI.

Gotchas and tips

Mastra is young and pre-1.0 — APIs still shift between minor versions. Commit a package-lock and read the changelog before upgrading. The storage layer defaults to LibSQL file-on-disk, which is convenient in dev but needs swapping for Postgres or Upstash in production.

Because Mastra sits on top of the Vercel AI SDK, any quirk there leaks through — including the occasional breaking change in tool-call formats between providers. Integration-test across models if you expect to swap.

Who it’s for

TypeScript teams tired of translating Python tutorials into JS. Tip: even if you only need one agent, start with a Workflow — retries and tracing are free and you’ll want them the first time a tool call times out.