Why We Evaluated Mastra
The expensive part of a TypeScript agent product usually arrives after the first successful model response. We need streaming, authenticated tools, conversation history, workflow checkpoints, tracing, and evaluations to behave consistently. Individually, those integrations are manageable. Together, they become a second application hidden beneath the product.
The production trade-off
Mastra consolidates workflows, memory, and HTTP integration, but production adoption still requires validation of recovery, isolation, and an equal-workload SDK comparison.
That is the bottleneck we wanted to examine with Mastra: can we replace that integration layer without inheriting a runtime we cannot operate?
Mastra combines a typed agent abstraction with graph-based workflows, storage interfaces, memory, and HTTP integration. We can use an agent for model-directed tool execution and explicit workflow control for business processes that require predictable branching or approval boundaries. Its value is architectural consolidation, not a faster language model.
What this review could not verify
This review is a source-verified architecture evaluation with a runnable worked example, not a completed deployment or load test. We did not execute Node packages, call a model, or run the Oya benchmark. We therefore report no measured latency, throughput, cold-start time, or memory footprint. The example output below is explicitly simulated.
We anchored the review in the Mastra 1.0 release, the repository, and the server-adapter reference. We also separated January’s release behavior from the broader adapter catalog visible in November. Installing latest today is not a reproduction of the original 1.0 release.
Our preliminary position: Mastra deserves a structured trial when workflow state and agent memory are already product requirements. For a stateless streaming endpoint with two tools, we would start smaller.
Express Smoke Test: Setup, Code, and Illustrative Output
We would begin with the supported scaffold rather than copy an old pre-1.0 tutorial:
npm create mastra@latest
For pnpm, we would use this scaffold command:
pnpm create mastra@latest
We would not silently substitute pnpm dlx mastra@latest. That invokes the mastra package executable, while the documented creation path uses the scaffold package. The available material does not establish that the bare dlx command creates an equivalent project. Check its help and intended subcommand before putting it into automation.
Node 20 compatibility is another explicit gate. Running TypeScript directly on newer Node versions does not prove that every current Mastra package supports Node 20. On a Node 20 evaluation machine, our first checks would be:
node --version
pnpm --version
for package in @mastra/core @mastra/express @mastra/hono @mastra/next; do
pnpm view "$package" version engines peerDependencies --json
done
If an engine requirement excludes Node 20, stop there: upgrade the runtime or deliberately select a compatible release set. tsx can execute TypeScript; it cannot repair unsupported runtime APIs.
A minimal Express route-registration test
We designed this smoke test to answer one narrow question: can the adapter expose an explicitly registered agent and generate its API description without making an LLM request?
Run it in an empty directory using an engine-compatible Node installation. This recipe resolves package versions at installation time; preserve the resulting lockfile and resolved versions before treating it as a reproducible fixture.
set -eu
printf '{"name":"mastra-adapter-smoke","private":true,"type":"module"}\n' \
> package.json
pnpm add --save-exact @mastra/core@latest @mastra/express@latest express
pnpm add -D --save-exact tsx typescript @types/node @types/express
mkdir -p src
cat > src/server.ts <<'TS'
import express from "express";
import { Mastra } from "@mastra/core";
import { Agent } from "@mastra/core/agent";
import { MastraServer } from "@mastra/express";
const probeAgent = new Agent({
id: "probe-agent",
name: "Probe Agent",
instructions: "Return concise answers. Never perform external actions.",
model: "openai/gpt-4o",
});
const mastra = new Mastra({
agents: { probeAgent },
});
const app = express();
app.use(express.json());
const server = new MastraServer({
app,
mastra,
openapiPath: "/openapi.json",
});
await server.init();
app.listen(4111, "127.0.0.1", () => {
console.log("Listening on http://127.0.0.1:4111");
});
TS
pnpm exec tsx src/server.ts > smoke.log 2>&1 &
server_pid=$!
trap 'kill "$server_pid" 2>/dev/null || true' EXIT
ready=0
for attempt in $(seq 1 60); do
if curl --fail --silent http://127.0.0.1:4111/api/agents \
> agents.json; then
ready=1
break
fi
sleep 1
done
if [ "$ready" -ne 1 ]; then
cat smoke.log
exit 1
fi
curl --fail --silent http://127.0.0.1:4111/openapi.json \
> openapi.json
node --input-type=module <<'JS'
import fs from "node:fs";
import assert from "node:assert/strict";
const agents = JSON.parse(fs.readFileSync("agents.json", "utf8"));
const spec = JSON.parse(fs.readFileSync("openapi.json", "utf8"));
assert.ok(JSON.stringify(agents).includes("probe-agent"));
assert.ok(spec.paths && Object.keys(spec.paths).length > 0);
console.log(JSON.stringify({
agentVisible: true,
openapiHasPaths: true,
modelGenerationRequested: false
}, null, 2));
JS
Illustrative stdout—not an observed execution result:
{
"agentVisible": true,
"openapiHasPaths": true,
"modelGenerationRequested": false
}
A model key is not used by the intended test path because we never request generation. Whether a particular pinned release eagerly validates provider configuration remains something this test must establish. A subsequent generation test needs an exported OPENAI_API_KEY and an available model.
Our negative control would construct Mastra without probeAgent and require the visibility assertion to fail. That distinguishes successful HTTP startup from successful agent registration.
Choosing the server boundary
We verified three distinct integration paths:
| Target | Integration surface | Our deployment consideration |
|---|---|---|
| Express |
@mastra/express; pass the app and Mastra instance to MastraServer, then await init()
|
Preserve Express-native authentication and middleware ordering |
| Hono |
@mastra/hono; use a typed Hono app and an appropriate serving adapter |
Hono-signature middleware fits this adapter directly |
| Next.js | Current catalog includes @mastra/next, installed with hono
|
Verify the pinned adapter’s Next.js setup and runtime requirements separately |
For a release-aligned 1.0 Next.js/full-stack setup, we would use mastra build. In our review of the current integration options, we also identified the dedicated @mastra/next adapter. We would not combine those instructions indiscriminately or infer Edge compatibility from the package name.
Implementation Risks Identified During Review
We did not execute the worked example, so these are implementation traps we identified during review—not failures we personally reproduced.
1. File placement is not registration
With server adapters, we must register agents on the Mastra instance passed to the adapter. File-based discovery does not run there.
We would use an explicit composition root, assembling agents, workflows, storage, and MCP servers in one reviewed module. CI should assert that expected resources appear through the HTTP boundary.
2. HTTP readiness is not worker readiness
In the current adapter lifecycle, init() registers routes and middleware; it does not start background workers. For scheduled workflows, event listeners, and the applicable recovery loop, we need mastra.startWorkers() in a persistent process, or a separate worker deployment.
Our smoke test deliberately omits workers because it tests registration only. A production readiness check must cover both API and worker health. We would also wire mastra.shutdown() into termination handling and give the platform enough shutdown time to match the configured drain behavior.
3. Middleware portability has limits
Mastra-configured middleware uses Hono’s signature. Non-Hono adapters can warn rather than mount that configuration.
We would keep Express authentication in Express-native middleware or use the adapter’s documented auth helpers. We would independently test raw application routes: registering Mastra authentication does not automatically establish that every route we add to the host framework is protected.
4. Memory defaults changed
For 1.0, semantic recall is disabled by default and lastMessages is 10. That is not a promise of unlimited conversation history, nor does adding storage automatically prove that an agent has memory configured.
We would explicitly configure memory and test a conversation that exceeds the history window. For regulated or multi-tenant workloads, thread ownership checks belong in the test suite alongside recall correctness.
Thread cloning shipped in 1.0, but we could not verify its method signature, copy semantics, or storage requirements from the available material. We would block that feature until tests establish message isolation, metadata handling, authorization, and subsequent-write behavior. A feature name is not sufficient evidence for a production API example.
5. Composite storage separates domains—not transactions
The 1.0 storage interface supports per-domain backends:
import { MastraCompositeStore } from "@mastra/core/storage";
import { WorkflowsPG, ScoresPG } from "@mastra/pg";
import { MemoryLibSQL } from "@mastra/libsql";
const storage = new MastraCompositeStore({
id: "composite",
domains: {
memory: new MemoryLibSQL({ url: "file:./local.db" }),
workflows: new WorkflowsPG({
connectionString: process.env.DATABASE_URL!,
}),
scores: new ScoresPG({
connectionString: process.env.DATABASE_URL!,
}),
},
});
This release-note configuration is useful for understanding the API boundary, not a recommendation to put production memory on an ephemeral filesystem. Splitting domains also does not establish atomic transactions across them. We would design retries and reconciliation around partial failures.
6. MCP adds another security boundary
Configured MCP servers can register routes through the adapter. That does not establish transport interoperability, credential propagation, or tenant isolation.
We would separately test MCP client calls, server exposure, tool cancellation, and authorization. With route prefixes, we would also verify discovery metadata paths rather than assuming every endpoint moves together. Default HTTP stream redaction is useful, but it does not sanitize all internal tracing callbacks.
Scale, Latency & Cost vs. Alternatives
We cannot substantiate a Mastra performance victory over Vercel AI SDK. We did not verify or execute the OyaAIProd/oya repository, and the available evidence contains no benchmark commands, pinned revision, workload definitions, or comparative results.
Consequently, there is no defensible “Mastra is X% faster” number in this review. Our comparison is about operational scope:
| Decision dimension | Mastra | What we would verify in an SDK baseline |
|---|---|---|
| Basic model streaming | Available within a broader framework | The integration surface needed for the same streaming behavior |
| Explicit workflows | Graph-based orchestration and stored execution state | How the baseline implements equivalent branching, persistence, and recovery |
| Conversation memory | Framework-level memory and storage integration | Equivalent persistence, history windows, and recall behavior |
| Server integration | Generated server or framework adapters | The deployment topology and HTTP boundary used for comparison |
| Evals and observability | Integrated surfaces | Equivalent evaluation and tracing coverage |
| Measured latency and resource usage here | Not measured | Not measured; we cannot rank performance |
Our benchmark design would have two tracks. The first isolates orchestration overhead using deterministic model and tool fixtures. The second uses a real provider and identical model settings, tool results, history, output limits, and retry policies.
We would report time to first token, total completion time, tool correctness, failed requests, tokens, process RSS, and storage operations. We would separate cold process startup from warm requests and alternate framework order to reduce bias from changes in provider performance over time. Concurrency steps should expose queueing and connection-pool pressure rather than collapse everything into one average.
A memory-disabled SDK endpoint is not a fair baseline for a memory-enabled Mastra agent. Neither is a direct SDK call versus a Mastra HTTP request.
Serverless is a topology decision
No cold-start measurements are available here. Our risk model includes module initialization, database connections, MCP client initialization, and platform request-duration limits. We would reuse instances where the platform permits, avoid local durable state, and keep long-lived workers outside request-only functions.
For sustained workflows, we would first evaluate a persistent Node deployment. That makes lifecycle behavior easier to inspect; it does not automatically make it cheaper or faster.
A practical break-even calculation
We would evaluate total cost as:
Engineering saved − migration and maintenance effort − additional infrastructure − any change in model usage.
For an illustrative—not measured—case:
- Loaded engineering cost: $120/hour
- Initial integration avoided: 80 hours
- Additional monthly operations: 8 hours, or $960
- Additional infrastructure: $150/month
That produces $9,600 in initial savings against $1,110 in monthly incremental expense: approximately 8.6 months before those savings are consumed.
If Mastra also saves 12 maintenance hours monthly, the ongoing balance changes by $1,440/month and becomes favorable under those assumptions. If it saves only a few hours of streaming integration, the initial argument weakens sharply.
We would also compare token usage. Different history windows, recall policies, or retries can change provider spend without any meaningful difference in framework execution speed.
Our Final Verdict: When to Deploy, When to Skip
Our verdict is proceed to a bounded production proof of concept, not an unconditional rollout.
Mastra offers a credible way to keep TypeScript agents, workflows, memory, and HTTP integration in one architecture. We see the strongest case when those requirements already exist—not when we are buying hypothetical future flexibility.
We would deploy after validation if:
- Our team owns a TypeScript-first service and needs explicit, stateful workflows.
- We can pin compatible package versions and commit the lockfile.
- Restart, recovery, idempotency, and tenant-isolation tests pass.
- Storage ownership, backups, and connection limits are explicit.
- We budget for domain-specific evals rather than treating built-in scoring as complete coverage.
- Our license review confirms whether any selected
ee/features require a production enterprise license.
We would hold off or choose a smaller stack if:
- The product is a stateless streaming endpoint with straightforward tools.
- Node 20 is mandatory but the selected release set has not been verified against it.
- We need proven thread-cloning semantics before implementation begins.
- Our rollout depends on unverified Oya benchmark results.
- Request-only serverless infrastructure must also host persistent workers.
- Deep Python ML integration is the central requirement.
We would authorize the next stage around three acceptance tests: route and auth correctness, workflow survival across process termination, and an equal-workload SDK comparison. Until those pass, “production-ready” describes a release milestone, not our system.
For adjacent options, explore our tools collection. If the difficult part is choosing the runtime and operational boundary rather than writing the agent, talk with us about the architecture. Our preference is simple: adopt the framework only when the integration work it saves outweighs the operational work it adds.
Top comments (0)