Mastra (29.7k GitHub stars, YC W25) is a TypeScript-first agent framework that bundles model routing, workflow orchestration, and human-in-the-loop primitives into one opinionated stack. It sits between lightweight LLM wrappers and heavyweight orchestration platforms, giving you agents, workflows, and state management without forcing you into a specific deployment model.
The interesting part is not that it exists. The interesting part is how it wires together three hard problems: abstracting 40+ model providers without leaking quirks, executing graph-based workflows with control-flow primitives, and suspending/resuming agent execution when humans need to approve decisions.
Model Routing Layer
Mastra's model interface abstracts OpenAI, Anthropic, Gemini, and 37 other providers into one API surface. The goal is to let you swap models without rewriting tool schemas or prompt templates.
How it works:
- Unified
generate()method accepts messages, tools, and config - Provider adapters normalize streaming, function calling, and token counting
- Model-specific quirks (like Anthropic's system message handling) are hidden behind the adapter layer
- You can route requests to different models based on cost, latency, or capability
Trade-offs:
| Approach | Benefit | Cost |
|---|---|---|
| Single provider SDK | Full feature access, no abstraction tax | Vendor lock-in, rewrite on migration |
| Mastra's unified interface | Swap models without code changes | Lowest-common-denominator features |
| Direct API calls | Maximum control, no framework overhead | Manual retry logic, streaming, tool parsing |
The abstraction works when your use case fits the common subset of LLM capabilities. It breaks when you need provider-specific features like Anthropic's prompt caching or OpenAI's structured outputs with strict schemas.
Workflow Engine Architecture
Mastra workflows are directed acyclic graphs (DAGs) where each node is a step and edges define execution order. You compose workflows using .then(), .branch(), and .parallel() primitives.
Execution model:
const workflow = new Workflow({
name: 'approval-flow',
triggerSchema: z.object({ amount: z.number() })
});
workflow
.step('validate', async ({ context }) => {
if (context.machineContext.amount > 1000) {
return { needsApproval: true };
}
return { needsApproval: false };
})
.branch({
when: ({ context }) => context.needsApproval,
then: workflow.step('suspend-for-approval', async ({ context }) => {
return context.suspend({ reason: 'high-value-transaction' });
}),
else: workflow.step('auto-approve', async () => {
return { approved: true };
})
})
.then('process', async ({ context }) => {
// Execute transaction
});
Under the hood:
- Each step returns a result object that flows into the next step's context
-
.branch()evaluates a predicate and routes to one of two sub-graphs -
.parallel()spawns concurrent step execution and waits for all to complete - The engine maintains a state machine tracking which steps have executed and what data they produced
Failure modes:
- If a step throws, the workflow halts unless you wrap it in error-handling logic
- Parallel steps that share mutable state can race (Mastra does not provide locking primitives)
- Long-running workflows need persistent storage or they lose state on server restart
Suspend and Resume Plumbing
Human-in-the-loop is where most agent frameworks hand-wave. Mastra implements suspend/resume by persisting workflow state to a storage backend and exposing a resume API.
How suspend works:
- A step calls
context.suspend({ reason, data }) - Mastra serializes the workflow state (executed steps, context data, next step pointer)
- State is written to the configured storage backend (Postgres, Redis, or in-memory)
- The workflow execution halts and returns a
suspendIdto the caller
How resume works:
- External system (UI, webhook, cron) calls
workflow.resume(suspendId, { decision }) - Mastra loads the serialized state from storage
- The workflow engine reconstructs the execution graph and context
- Execution continues from the suspended step with the injected decision data
Storage layer options:
- In-memory: Fast, zero config, state lost on restart
- Postgres: Durable, supports concurrent workflows, requires schema migrations
- Redis: Fast durable storage, TTL-based expiration, no complex queries
Security boundaries:
- Suspend state includes full workflow context, so sensitive data (API keys, PII) must be filtered before serialization
- Resume endpoints need authentication to prevent unauthorized workflow manipulation
- No built-in sandboxing for tool execution (you must wrap tools in your own isolation layer)
Tool Execution Model
Mastra agents call tools by passing function schemas to the LLM and executing the selected tool when the model responds with a function call.
Tool registration:
const agent = new Agent({
name: 'support-agent',
model: openai('gpt-4'),
tools: {
searchDocs: {
description: 'Search documentation',
parameters: z.object({ query: z.string() }),
execute: async ({ query }) => {
// Tool implementation
}
}
}
});
Execution flow:
- Agent sends messages + tool schemas to LLM
- LLM responds with function call (tool name + arguments)
- Mastra validates arguments against Zod schema
- Tool's
execute()function runs with validated arguments - Tool result is appended to message history
- Agent sends updated history back to LLM for next turn
What's missing:
- No built-in rate limiting or quota management for tool calls
- No automatic retry logic if a tool throws (you must implement in the tool)
- No sandboxing or resource limits (a tool can block the event loop or consume unbounded memory)
- No observability hooks for tool execution time or failure rates
Deployment Shapes
Mastra runs in three modes:
Standalone server:
- Exposes HTTP endpoints for agent and workflow execution
- Handles state persistence and resume logic
- You manage scaling, load balancing, and observability
Embedded in Next.js:
- Agents and workflows run in API routes or server actions
- State persists to your Next.js database
- Tight coupling to your application's deployment lifecycle
Embedded in Node.js:
- Import Mastra as a library in any Node process
- Useful for background workers, CLI tools, or serverless functions
- You control the runtime environment and dependencies
When to Use Mastra
Good fit:
- You want TypeScript end-to-end (no Python interop)
- You need to swap LLM providers without rewriting code
- Your workflows have explicit control flow (not just agent loops)
- You need human approval gates in agent execution
- You're building on Next.js or React and want tight integration
Poor fit:
- You need provider-specific features (prompt caching, structured outputs with strict schemas)
- Your tools require sandboxing or resource limits
- You need distributed workflow execution across multiple machines
- You want built-in observability (tracing, metrics, logs)
- You're building in Python or another language
Technical Verdict
Mastra solves the "batteries included" problem for TypeScript agent systems. It gives you model abstraction, workflow orchestration, and state management without forcing you into a specific deployment model or cloud platform.
The model routing layer works when you stay within the common subset of LLM capabilities. The workflow engine is clean but lacks distributed execution primitives. The suspend/resume mechanism is the standout feature, but you must handle security boundaries and storage durability yourself.
Use Mastra when you want an opinionated starting point for agent systems and you're willing to trade flexibility for velocity. Avoid it when you need fine-grained control over tool execution, distributed workflows, or provider-specific LLM features.
The framework is young (YC W25), so expect API churn and missing observability primitives. The architecture is sound, but production deployments will need additional layers for rate limiting, monitoring, and error recovery.
Top comments (0)