Mastra: when FDEs should pick a TypeScript agent framework with workflows, memory and evals built in

The client’s backend runs on Node and TypeScript. Their team will take over the agent system the moment you leave the site. At that point, choosing a framework is no longer a matter of taste: it decides who can still change the code six months later.

Mastra is a serious candidate for exactly this situation. The official documentation defines it as a TypeScript framework for building agents and AI applications. The official repo brings agents, workflows, memory, evals and MCP together in one place.

Behind it is the team that built Gatsby, with three co-founders, Sam Bhagwat (CEO), Shane Thomas and Abhi Aiyer, who started the company in 2024. For you, the useful question is not whether Mastra is good, but when it is the right choice at a client site and what you need to learn to use it from day one.

Choose for the maintainers, not for the demo

A deployment succeeds only if the client’s team can still change it after you leave. If their backend is TypeScript, bringing in a Python service to run agents means one more runtime, one more deployment pipeline and a group of people who have to learn another language. Mastra avoids that cost because the agents live in the same language and the same repo as everything else.

The second reason is that Mastra already ships four things an agent engagement usually has to build: orchestrating steps, remembering users, connecting tools through MCP, and scoring output quality.

Stitch those four together from four libraries and most of your time on site goes into wiring. Conversely, if the client’s team works purely in Python, this advantage mostly disappears, and you should think again.

Workflow or agent: where is the line?

Mastra’s documentation is explicit: use a workflow when the task is defined up front, has multiple steps and must run in a specific order. Workflows run on a graph-based engine, and every run can pause, resume and stream its results. Only the parts that remain ambiguous, where the model has to choose the next step itself, should go to an agent.

This line matters to an FDE when the client wants to know which step runs first and which step needs someone to sign off. Pausing and resuming is exactly where you put a human approver into the flow without writing your own state machine.

Picture a refund flow with human approval

Suppose the client is a retailer that wants to automate refund requests. You build a four-step workflow: classify the request, look up the order, decide, then draft the reply. At the decision step, if the amount exceeds a threshold set by the client, the workflow pauses and waits for a staff member to approve before continuing.

The sketch below only illustrates the logic of that step and an accompanying scorer. It is pseudocode, not exact syntax; check the real function names in the Mastra v1 documentation.

// Pseudocode: illustrates the logic, not the exact Mastra v1 API
const decide = step(async ({ refund, suspend, resumeData }) => {
  if (refund.amount > APPROVAL_THRESHOLD && !resumeData) {
    // The run stops here until a staff member approves and resumes it
    return suspend({ orderId: refund.orderId, reason: "needs_approval" });
  }
  return { approved: resumeData ? resumeData.approved : true };
});

// Rule-based scorer: does the reply mention the correct order ID?
const mentionsOrderId = (output, refund) =>
  output.includes(refund.orderId) ? 1 : 0;

A common mistake is to cram the parts that need judgement into the workflow’s fixed if-else chain, such as deciding whether a vague refund reason is valid. Following the line the documentation draws, that part belongs to an agent, while the workflow keeps only the clearly ordered steps and the approval pause.

Mix the two and you end up with a workflow that swells with every exception the client mentions. The first thing to do on site is sit down with the operations team, draw the steps on a whiteboard, and mark which steps require human approval and which need judgement. That drawing is very nearly the workflow design.

What does the agent remember, and in which layer?

Mastra’s memory has several layers, and the refund flow needs all three. Message history keeps the last N messages of the conversation, enough that the agent does not ask again for the order ID it was just given.

Working memory stores structured, persistent data about the user, such as name, preferences and goals. That lets the agent remember this customer wants the money back on a card rather than a wallet, even in a later conversation.

Semantic recall retrieves old messages by meaning rather than keywords. A line like “last time you sent the wrong colour” still finds last month’s complaint even if the user does not repeat the same words.

The easiest mistake is to push everything into one layer. Put customer preferences in message history and they drift away as the conversation grows; rely on semantic recall for structured data such as the refund method and the result depends on whether the meaning-based search happens to hit.

Decide up front which information is a fixed profile and which is just context.

Score before the client does

Evals in Mastra are called scorers: automated tests that grade an agent’s output in three ways, model-graded, rule-based and statistical. In the refund flow, a rule-based scorer like the one in the sketch above checks the order ID. A model-graded scorer judges whether the tone is polite and the reply follows policy.

Scorers can run in two places. In CI/CD they become regression tests: every time you change a prompt, you rerun them on a set of sample conversations and block the merge if scores drop. In production they run live in the background with sampling, without blocking the agent’s response or the workflow’s execution.

The live mode is what gives you numbers when the client asks whether the agent got worse this week than last. Agree on two or three scorers with them in the first week, before anyone complains.

Limits to raise with the client up front

Mastra’s licence has two layers. The core is Apache 2.0, while code in the ee/ directories falls under the Mastra Enterprise License, which is source-available. The client’s legal team may ask about this, so check in advance where the features you plan to use live.

The version milestone has practical consequences too. Mastra v1 launched in January 2026; the documentation advises new projects to start directly on v1 and has a dedicated upgrade guide. Tutorials and sample code written before then may no longer match, so when looking things up, prefer the official v1 documentation.

In what order to learn it, and how to test yourself

A sensible order follows the example flow above. Start with a workflow that has an approval pause, because that is where suspend/resume shows its value most clearly when the client wants to keep sign-off rights. Then add working memory to an agent, and finally wire scorers into CI.

Final exercise: rebuild the refund flow with a configurable approval threshold, store the refund method in working memory, then write a rule-based scorer that checks the order ID. You pass when a request over the threshold stops in the right place, resumes after approval, and the CI scorer turns red if you deliberately remove the order ID from the reply.

In career terms, a small repo that shows all three carries far more weight than a demo chatbot. On your CV, write in terms of outcomes, for example “designed a TypeScript agent workflow with a manual approval step and CI scorers that block quality regressions”.

Frameworks will keep changing, but the method holds: separate the procedural parts from the parts that need model reasoning, put the human approver in the right place, and measure quality before the client has to measure it for you.