English for Mastra AI Agent Developers

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 supportAgent with three tools — lookupOrder, refundPayment, and escalateToHuman — 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 lookupOrder with 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

1. Write two sentences explaining, to a non-technical product manager, why an agent needs “memory” to feel useful in a support chatbot.
2. Describe, in your own words, the difference between a “tool” and a “workflow step” as if explaining it to a new team member.
3. Write a short Slack message reporting that an eval caught a regression after a model upgrade, including what you’ll do next.

Related Resources

• English for LangChain Developers
• AI Agents Vocabulary
• Vector Database Vocabulary

Navigating the Nuances of Remote Collaboration – Beyond Literal Translation

Mastra’s strength lies in its ability to orchestrate complex workflows involving large language models and retrieval systems. This often involves international teams communicating about these intricate processes, which inherently introduces challenges beyond simply translating words. The subtle differences in phrasing, expectations around clarity, and even the level of detail required can significantly impact collaboration efficiency and ultimately, the success of your agentic projects. Many non-native speakers understandably focus on precise word choice, but it’s equally critical to understand how these concepts are discussed professionally – focusing less on literal translation and more on conveying intent and context effectively.

One common pitfall is over-formalizing communication. While clarity is paramount, excessively technical jargon or overly elaborate phrasing can be misinterpreted across cultures and experience levels. A simple “Let’s iterate on this” might come across as demanding in some contexts, while “We need to refine the response” could feel condescending in others. Learning to express ideas concisely and focusing on actionable steps – like requesting a “minor adjustment” or suggesting a “quick test” – is key. Similarly, when providing feedback during a code review, avoid simply stating what’s wrong; instead, frame it as a suggestion for improvement: “Could we explore adding some contextual information here to improve the agent’s understanding?” A Slack message requesting clarification on a complex RAG pipeline should be direct and focused on the specific aspect needing attention: “Regarding the vector database integration – are we using embeddings from Cohere or OpenAI?”

Furthermore, nuanced discussions about evaluation metrics require careful phrasing. Instead of saying “The model failed,” which can sound judgmental, try “We need to revisit the evaluation criteria for this task. The current metrics aren’t adequately capturing [specific aspect].” This shifts the focus to a collaborative process of refinement rather than assigning blame. Consider also that expectations around documentation and PR descriptions vary – some teams demand exhaustive detail, others prioritize brevity focused on functionality.

Finally, don’t be afraid to ask for clarification if something isn’t clear. It’s far better to admit confusion than to proceed based on assumptions. A simple “Could you elaborate on that?” or “Just to confirm, are we aiming for X outcome?” demonstrates engagement and a desire for understanding – qualities valued in any collaborative environment.

Here’s an example of how the faiss library is used within a Mastra workflow:

# Example using faiss to index embeddings for RAG retrieval (simplified)
python -m faiss.index create --type InnersProduct --dim 128 --nlist 100 ./my_embedding_index

This command initializes an FAISS index, a popular tool for efficient similarity search within vector databases, often utilized in Mastra’s RAG pipelines to quickly retrieve relevant information based on semantic similarity. The --type InnersProduct specifies the metric used for comparing vectors, and --dim 128 sets the dimensionality of the embeddings (representing the vector space). --nlist 100 indicates that we’re creating an index with 100 lists to store the vectors.