English for Mastra AI Agent Developers
Key English vocabulary and phrases for building AI agents with Mastra — workflows, tools, memory, evals, and RAG pipelines — for TypeScript developers working on cross-border agentic teams.
Mastra is a TypeScript framework for building AI agents, workflows, and retrieval-augmented generation (RAG) pipelines. If you’re joining a team that ships agentic products with Mastra, you’ll be discussing “tools,” “workflows,” “memory,” and “evals” constantly — often in stand-ups and design docs where precise vocabulary matters as much as correct code. This guide walks through the terms and the sentences you’ll actually use when explaining a Mastra-based system to teammates, stakeholders, or interviewers.
Core Building Blocks
Agent
An agent in Mastra is an LLM-backed entity configured with instructions, a model, and a set of tools it can call. Agents differ from a single prompt call because they can decide, at runtime, which tool to invoke and when to stop.
“We defined a
supportAgentwith three tools —lookupOrder,refundPayment, andescalateToHuman— and gave it clear instructions about when to escalate rather than guess.”
Tool
A tool is a typed function the agent can call — described with a name, a description, and an input schema (usually Zod) so the model knows exactly what arguments to provide.
“The tool’s description matters more than people expect — if it’s vague, the agent calls it at the wrong moment or with malformed arguments.”
Workflow
A workflow is a deterministic, multi-step pipeline that can call agents and tools in sequence, in parallel, or conditionally — with retries and branching built in. Workflows give you control over parts of the pipeline you don’t want left entirely to the model’s judgment.
“We moved the payment step out of the agent’s free-form reasoning and into a workflow step — it’s too risky to let the model decide when to charge a card.”
Step
Within a workflow, a step is a single unit of work with defined inputs and outputs. Steps can be chained, run in parallel with .parallel(), or made conditional.
“Each step logs its own input and output, so when the workflow fails at step four, we don’t have to guess what state it was in.”
Memory and Context
Memory
Memory in Mastra persists conversation history and derived facts across sessions, so an agent can recall earlier interactions instead of starting from a blank context every time.
“Without memory, the agent kept asking the same qualifying questions every session — once we wired up persistent memory, it remembered the user’s plan tier and stopped repeating itself.”
Working Memory
Working memory is a smaller, structured subset of memory the agent actively maintains and updates — useful for tracking things like a user’s stated preferences or an in-progress task’s status.
Semantic Recall
Semantic recall retrieves relevant past messages by embedding similarity rather than strict recency, so an agent can surface a fact from three weeks ago if it’s relevant to the current question.
“Semantic recall pulled up the user’s earlier complaint about slow exports, which was exactly the context the agent needed to answer their follow-up.”
Retrieval-Augmented Generation (RAG)
Chunking
Chunking splits source documents into smaller pieces before embedding, so retrieval returns focused, relevant passages instead of entire documents.
“We switched from fixed-size chunking to recursive chunking that respects markdown headings — retrieval quality improved noticeably.”
Vector Store
A vector store holds embeddings and supports similarity search. Mastra integrates with several — Pinecone, PgVector, Qdrant, and others.
Retriever
A retriever is the component that queries the vector store and returns the top-matching chunks for a given query, which are then injected into the agent’s context.
“The retriever was returning stale chunks because we forgot to re-index after the docs update — always a good first thing to check when RAG answers feel out of date.”
Evaluation and Observability
Eval
An eval is an automated, scored test of an agent’s output — checking things like faithfulness to source material, toxicity, or answer relevance. Evals let you catch regressions before they reach production.
“We added a faithfulness eval that flags any response not grounded in the retrieved documents — it caught a hallucination during our last model upgrade.”
Trace
A trace is the full recorded path of an agent’s execution — every tool call, every model completion, every step — used for debugging and observability.
“When the refund flow behaved unexpectedly, the trace showed the agent had called
lookupOrderwith the wrong ID format — an easy fix once we could see it.”
Guardrail
A guardrail is a rule or check that constrains agent behaviour — for example, blocking a tool call above a certain dollar amount without human approval.
“We added a guardrail so any refund over $200 pauses the workflow and waits for a human to approve it.”
Deployment Vocabulary
Streaming
Streaming sends partial agent output to the client as it’s generated, rather than waiting for the full response — important for perceived responsiveness in chat interfaces.
Human-in-the-Loop
Human-in-the-loop describes a workflow step that pauses execution and waits for a person to approve, reject, or edit before continuing.
“The workflow calls
suspend()before the refund step and waits for a support lead to approve it — that’s our human-in-the-loop checkpoint.”
Key Phrases for Discussing Mastra Systems
| Situation | Phrase |
|---|---|
| Explaining why you used a workflow instead of pure agent reasoning | ”We wanted deterministic control over the payment step, so we moved it into a workflow instead of leaving it to the agent’s judgment.” |
| Describing a memory bug | ”The agent lost context between sessions because memory wasn’t configured to persist — it’s fixed now.” |
| Justifying an eval | ”We added this eval specifically because a previous model upgrade introduced a subtle hallucination we didn’t catch until a customer reported it.” |
| Discussing tool design | ”The tool description needs to be unambiguous — otherwise the agent picks the wrong tool for edge cases.” |
Practice Exercise
- Write two sentences explaining, to a non-technical product manager, why an agent needs “memory” to feel useful in a support chatbot.
- Describe, in your own words, the difference between a “tool” and a “workflow step” as if explaining it to a new team member.
- Write a short Slack message reporting that an eval caught a regression after a model upgrade, including what you’ll do next.