Mastra 1.0: TypeScript-First AI Agent Framework Developer Guide

TypeScript developers building production agents have watched two separate ecosystems grow in parallel: LangChain JS on one side, and a cluster of smaller, more opinionated frameworks on the other. Mastra started as the latter — a project out of the Gatsby team — and by January 2026 it shipped a 1.0 release that landed in a different category. It reached 22,000+ GitHub stars and 300,000+ weekly npm downloads with a single opinionated bet: TypeScript-first, batteries-included, native multi-protocol.

Effloow Lab inspected @mastra/core@1.37.0 on 2026-05-27 and confirmed the package manifest. The lab-run note is at data/lab-runs/mastra-1-0-typescript-agent-framework-guide-2026.md. No live LLM calls were made — API keys are not available in this environment. All code examples in this guide are drawn from official Mastra documentation and match the confirmed package API surface.

What makes Mastra different from LangChain JS

The design decision that separates Mastra from LangChain JS is scope. LangChain JS is a toolkit for assembling components: you bring your own server, your own storage, your own observability, and wire them together. Mastra is a runtime: it ships a built-in HTTP server via Hono, cron-based workflow scheduling via Croner, an embedded dev studio UI, OpenTelemetry tracing, and Zod-typed tool definitions — all in one package.

The tradeoff is flexibility vs. convention. If you want to swap every layer, LangChain JS gives you that. If you want a typed, tested, opinionated stack where agents, workflows, tools, memory, and observability all share a single module boundary, Mastra is the pick.

Installing Mastra

The recommended starting point is the scaffold command:

npm create mastra@latest my-agent-app --default --llm anthropic

LLM provider options: openai, anthropic, groq, google, cerebras, mistral. The --default flag skips the interactive prompt and creates a starter project immediately.

For existing projects, add the core package directly:

npm install @mastra/core

Verified on 2026-05-27: @mastra/core@1.37.0 (Apache-2.0, 56 MB unpacked, 31 production dependencies).

Defining an agent

A Mastra agent wraps an LLM and a list of tools. The agent decides at runtime which tools to call and in what order — the framework handles the tool-call loop.

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

const getWeatherTool = createTool({
  id: 'get_weather',
  description: 'Returns current weather for a city',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number(), condition: z.string() }),
  execute: async ({ context }) => {
    // Replace with real API call in production
    return { temp: 22, condition: 'Partly cloudy' };
  },
});

const weatherAgent = new Agent({
  name: 'WeatherAgent',
  instructions: 'You are a helpful weather assistant.',
  model: anthropic('claude-haiku-4-5'),
  tools: { getWeatherTool },
});

const response = await weatherAgent.generate('What is the weather in Tokyo?');
console.log(response.text);

The createTool helper enforces Zod schemas on both input and output. If the LLM calls the tool with a malformed argument, Mastra rejects it before your execute function runs.

Workflows: graph-based agent orchestration

Mastra's workflow engine is a graph executor with explicit step boundaries. Unlike a bare agent loop, workflows let you define conditional branches, parallel steps, and retry logic without tangling them into prompt instructions.

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

const summarizeStep = createStep({
  id: 'summarize',
  inputSchema: z.object({ text: z.string() }),
  outputSchema: z.object({ summary: z.string() }),
  execute: async ({ inputData }) => {
    // LLM call here
    return { summary: `Summary of: ${inputData.text.slice(0, 50)}...` };
  },
});

const translateStep = createStep({
  id: 'translate',
  inputSchema: z.object({ summary: z.string() }),
  outputSchema: z.object({ translated: z.string() }),
  execute: async ({ inputData }) => {
    return { translated: `[JA] ${inputData.summary}` };
  },
});

const pipeline = createWorkflow({
  name: 'SummarizeAndTranslate',
  triggerSchema: z.object({ text: z.string() }),
})
  .step(summarizeStep)
  .then(translateStep)
  .commit();

The .commit() call compiles the DAG and validates that every step's input schema is satisfied by the prior step's output. This catches wiring errors at startup rather than at runtime.

Native MCP support

Mastra's @mastra/core@1.37.0 declares @modelcontextprotocol/sdk: ^1.29.0 as a direct dependency. That means MCP connectivity is built in — no separate plugin install.

import { MCPClient } from '@mastra/core/mcp';

const client = new MCPClient({
  servers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
    },
  },
});

const tools = await client.getTools();
// tools is a Mastra-typed ToolSet ready to pass to any Agent

This pattern exposes any MCP server's tools to Mastra agents without writing glue code. The getTools() call wraps MCP tool descriptors into Mastra createTool wrappers automatically.

Native A2A protocol support

A more unusual feature: Mastra ships @a2a-js/sdk: ~0.3.13 as a core dependency. A2A (Agent-to-Agent, donated to the Linux Foundation in April 2025) is the cross-vendor protocol for agent-to-agent task delegation. This means a Mastra agent can act as both an A2A client (delegating to external agents) and an A2A server (receiving tasks from other frameworks like LangGraph, CrewAI, or ADK).

import { A2AServer } from '@mastra/core/a2a';

const server = new A2AServer({
  agent: weatherAgent,
  port: 4000,
});

await server.start();
// Exposes the agent at /.well-known/agent-card.json for A2A discovery

This is production-relevant because it makes Mastra agents interoperable with the growing ecosystem of A2A-compatible frameworks without any translation layer.

Mastra Studio

Running npm run dev starts two processes: the agent HTTP server and Mastra Studio at http://localhost:4111. Studio is a local UI for testing agents, inspecting workflow runs, reviewing traces, and managing memory threads. It replaces the manual curl → read-logs cycle during development.

The dev server launches with:

npx mastra dev

Studio does not require a Mastra Cloud account. It runs entirely from your local Node process.

Memory: cross-session context

Mastra's memory system stores conversation threads and working memory across sessions. By default it uses LibSQL (a SQLite fork), with optional adapters for PostgreSQL, Pinecone, and others.

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

const memory = new Memory({
  storage: new LibSQLStore({ url: 'file:mastra.db' }),
});

const agentWithMemory = new Agent({
  name: 'PersonalAssistant',
  model: anthropic('claude-haiku-4-5'),
  memory,
});

When memory is attached, each agent.generate() call receives the thread's prior messages and working memory snapshot automatically. You do not need to manage message history manually.

Deployment options

Mastra agents expose a Hono HTTP server. The deployment target is any Node.js host that runs HTTP servers: AWS Lambda, Cloud Run, Vercel, Railway, Fly.io, or bare containers.

For Cloud Run:

mastra deploy --platform cloudrun --project my-gcp-project --region us-central1

The CLI packages the project, builds a container image, and deploys. OpenTelemetry tracing wires to Cloud Trace automatically when GOOGLE_CLOUD_PROJECT is set.

Comparison: Mastra vs LangChain JS vs Genkit

When to use Mastra

Common setup mistakes

Installing the wrong package. The entry point is @mastra/core, not mastra. Installing mastra (the CLI) without @mastra/core (the runtime) gives you the scaffold tool but not the agent SDK.

Skipping the LLM provider adapter. Mastra uses the AI SDK as its model layer. You need to install the provider separately — e.g., npm install @ai-sdk/anthropic — in addition to @mastra/core.

Calling agent.generate() without awaiting properly. Mastra agents return a Promise. Missing await gives a pending Promise object instead of the response text.

Not calling .commit() on workflows. Uncommitted workflows throw at execution time with an unhelpful error. Always call .commit() after the final .step() or .then() chain.

Frequently Asked Questions

Q: Is Mastra free to use in commercial projects?

The core framework (@mastra/core) is Apache-2.0 licensed. You can use it, modify it, and build commercial products on top of it without paying Mastra. Mastra Cloud (the hosted service) is a paid offering, but it is not required to run agents.

Q: What is the difference between Mastra and the Vercel AI SDK?

The Vercel AI SDK (ai package) is a low-level model interaction layer: it handles streaming, tool call parsing, and provider adapters. Mastra builds on top of the AI SDK to add agent orchestration, workflows, memory, MCP connectivity, A2A protocol support, and a dev studio. They are complementary, not competing.

Q: Does Mastra support streaming responses?

Yes. agent.stream() returns an async iterable of text chunks. The studio and the built-in HTTP server handle streaming through Hono's SSE support.

Q: Can I use Mastra with open-source models like Llama or Mistral?

Yes, through the AI SDK's Ollama or OpenAI-compatible adapter:

import { createOpenAI } from '@ai-sdk/openai';

const ollama = createOpenAI({
  baseURL: 'http://localhost:11434/api',
  apiKey: 'ollama',
});
const model = ollama('llama3.1:8b');

Any OpenAI-compatible endpoint works as a model provider.

Q: How does Mastra handle tool execution errors?

By default, Mastra catches tool execution errors and returns them to the LLM as a tool result with an error message. The agent can then retry or fall back. You can configure retry behavior per tool with retryConfig: { maxRetries: 3, delay: 1000 }.