Skip to content
ZajLibrary

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.

The Mastra handbook path

The Mastra handbook path 1. Concepts (the vocabulary) → 2. Architecture (how it fits) → 3. Agents (build one) → 4. Workflows (orchestrate) → 5. Deployment (ship it) Concepts the vocabulary Architecture how it fits Agents build one Workflows orchestrate Deployment ship it
Vocabulary first (Concepts), then how it fits together (Architecture), then hands-on (Agents → Workflows), then shipping it (Deployment).

The mental model

Section titled “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.

Mastra runtime ownership

Runtime ownership diagram Server routes call a single runtime. The runtime coordinates workflows, agents, tools, storage, and observability. A red dashed line shows the anti-pattern where routes bypass the runtime and import step functions directly. User Prompt editor · chat · live cards Server Route auth · workspace · credits Runtime Registry brain: knows every part runManager commands Workflows steps · checkpoints Agents orchestrator + workers Tools search · image · validate Storage + DB snapshots · events · ledger Observability Langfuse · logs · cost anti-pattern: route imports step/tool directly
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

Section titled “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 of these is defined precisely on the Concepts page.

When to reach for Mastra

Section titled “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

Section titled “Keep going”