Mastra Core

@mastra/core is the flagship package of the Mastra framework, a TypeScript toolkit for building AI agents, workflows, and retrieval-augmented generation (RAG) pipelines. It centers on a single Mastra orchestration class that wires together agents, tools, workflows, memory, storage, and observability through a typed, dependency-injection-style configuration object, so teams can swap model providers, vector stores, and persistence backends without touching business logic.

Agents built on @mastra/core reason over tools and can run as standard in-process loops or as durable, workflow-backed executions that suspend and resume across process restarts. The package ships a graph-based workflow engine for explicit multi-step orchestration, a model router that normalizes access to 40+ LLM providers behind one interface, native support for both Model Context Protocol (MCP) and Agent-to-Agent (A2A) protocols for tool and agent federation, and a pluggable storage/memory layer supporting semantic recall across backends like PostgreSQL, LibSQL, and MongoDB via companion packages.

What You Get

• A central Mastra orchestration class for registering agents, workflows, tools, storage, and observability through one typed config
• A graph-based workflow engine with .then()/.branch()/.parallel() control flow and built-in suspend/resume via durable storage
• A model router giving one interface to 40+ LLM providers, including OpenAI, Anthropic, and Google
• Native MCP and A2A protocol support for exposing and consuming agents and tools across systems
• A pluggable memory and storage layer with semantic recall, backed by PostgreSQL, LibSQL, MongoDB, and other stores via companion packages

Common Use Cases

• Building production AI agents that call tools, retain conversation memory, and resume long-running tasks after interruption
• Orchestrating multi-step LLM workflows with explicit branching, parallelism, and human-in-the-loop approval steps
• Standing up MCP servers that expose an app’s agents and tools to any MCP-compatible client
• Adding retrieval-augmented generation (RAG) to an app with a storage-agnostic vector and embeddings interface

Under The Hood

Architecture A central Mastra class (src/mastra/index.ts) acts as a dependency-injection-style orchestrator, wiring in agents, workflows, tools, memory, storage, observability, schedules, server, and licensing through one typed configuration surface. Pluggable interfaces (a composite storage interface, a model-gateway interface, a deployer interface, an observability-exporter interface) let backends be swapped without touching core logic. Agents support both a traditional in-process tool-calling loop and a “durable” execution path that runs the agent as a resumable workflow backed by storage, while the workflow engine itself provides explicit run-scoping and suspend/resume. Cross-cutting concerns such as feature telemetry, observability context propagation, and lifecycle hooks are wired centrally through the Mastra class rather than scattered per module, so nearly every one of the package’s 40+ top-level subsystems is registered and resolved through a single composition root.

Tech Stack The package is TypeScript-first (99%+ of the monorepo by bytes), ESM-native with dual ESM/CJS output built via tsdown, and managed as a pnpm + Turborepo monorepo. Zod is a peer dependency used for schema validation, with ajv also present for JSON-schema needs. Model access is abstracted over multiple pinned versions of the AI SDK provider-utils package, and agent-to-agent communication is supported against two concurrent A2A SDK versions for compatibility. The HTTP layer is built on Hono, telemetry integrates PostHog, scheduling uses croner, and async control flow leans on p-retry and p-map. Testing runs on Vitest, and linting combines the fast Rust-based oxlint with ESLint.

Code Quality The core package alone carries roughly 900 unit test files under src/, run via a dedicated test:unit Vitest script. Errors flow through a shared MastraError/MastraBaseError hierarchy with explicit domain and category enums rather than raw throws or silent swallowing. Naming is consistent (kebab-case files, PascalCase classes), import type is used pervasively to keep builds lean, and tsc --noEmit strict type-checking runs as a separate CI-gated script alongside a dedicated changed-test-gate workflow, e2e test suite, and major-version-check workflow.

What Makes It Unique Mastra’s durable-agent execution model runs agent loops as resumable workflow executions backed by storage, going beyond typical agent frameworks that only checkpoint at the workflow level. Its model router normalizes 40+ LLM providers behind one generated interface, and it supports both MCP and A2A protocols simultaneously (versioned against two different A2A SDK releases) for interoperating with external tools and other agents. Combined with the DI-style central orchestrator treating agents, workflows, and storage as swappable registered components, this gives Mastra a notably more structured composition model than many peer agent frameworks.