Mastra

AI Engine · Handbook

Mastra is an open-source TypeScript framework for building AI agents and agentic applications. It gives you batteries-included primitives — agents, tools, workflows, memory, RAG, evals, and observability — on top of the Vercel AI SDK, so you get a consistent, provider-agnostic way to ship AI features without re-inventing the runtime each time.

Read this handbook in order

The pages build on each other. New to Mastra? Follow the path below — each stage assumes the previous one.

The Mastra handbook path

Vocabulary first (Concepts), then how it fits together (Architecture), then hands-on (Agents → Workflows), then shipping it (Deployment).

The mental model

Mastra centers on one runtime — a single Mastra instance that you register your agents, tools, and workflows on. Your app (a server route, a job, a CLI) talks to that runtime; the runtime owns execution, memory, and telemetry. The golden rule that the architecture enforces:

Routes call the runtime. The runtime calls everything else. A route should never import a workflow step or a tool directly — it asks the Mastra instance, which owns the wiring.

Play flow

Mastra runtime ownership

Press Play flow to walk a prompt from the server route, through the central Mastra runtime, out to the agent / workflow / tools / storage, and back. Runtime authority Anti-pattern — bypasses the runtime

Core primitives at a glance

Primitive	What it is	Why it exists
Mastra instance	The central runtime + registry.	One place owns config, agents, workflows, storage, telemetry.
Agents	An LLM + instructions + tools + memory.	The unit that reasons and decides which tools to call.
Tools	Typed functions an agent (or workflow) can call.	Give the model real capabilities, with schema-validated I/O.
Workflows	Graph of steps with branching, parallelism, suspend/resume.	Deterministic, durable orchestration around the non-deterministic model.
Memory	Working + recall (semantic) memory across threads.	Agents remember context within and across conversations.
RAG	Chunk → embed → store → retrieve pipeline.	Ground answers in your own documents.
Voice	Unified TTS / STT / speech-to-speech.	Let agents speak and listen, provider-agnostic.
Scorers / Evals	Automated quality checks on agent output.	Measure quality instead of vibe-checking.
Observability	OpenTelemetry traces + integrations.	See every model call, tool call, and step in production.
Multi-agent	Supervisor agent delegating to specialists.	Split big problems across coordinated agents.
MCP	Client + server for the Model Context Protocol.	Consume external tools, or expose yours to other agents.

Each primitive is named on the Concepts page and gets a hands-on deep-dive of its own — follow the links above or the path below.

When to reach for Mastra

Good fit

• You’re in the TypeScript/Node ecosystem and want one framework instead of gluing libraries together.
• You need agents + deterministic workflows (multi-step, branching, human-in-the-loop), not just one-shot completions.
• You want memory, RAG, eval, and tracing to come from the same place, provider-agnostic.

Maybe not

• A single, stateless model call with no tools — the Vercel AI SDK alone may be enough.
• A Python-first stack where the team is already invested in another framework.

Keep going

Foundations

• Concepts — define every primitive (the vocabulary).
• Architecture — how a request flows and why the runtime owns it.

Build

• Building agents — the minimal end-to-end agent.
• Tools — the typed contract behind every action.
• Workflows — steps, branching, and suspend/resume.

Deep dives

• Memory — continuity within and across conversations.
• RAG — ground answers in your own documents.
• Multi-agent systems — supervisor + specialists.
• Evals & scorers — measure quality, not vibes.
• Observability — trace every call in production.
• MCP — interoperate with the wider ecosystem.

Ship

• Deployment — dev → build → production.