S02E01 · Agentic Primitives: MEGA lesson video by Angie Jones
Angie Jones explains how instructions, tools, memory, and model choices shape a customer service agent, then demonstrates tracing its agent loop in Mastra Studio. The lesson also covers limiting model steps and diagnosing mismatches between an agent’s instructions and capabilities.
videoAngie Jones · hq.mega.dev · Saved Nov 19, 2026
mega course, agent infrastructure, agent memory, tracing, tool calling
Transcript of the lesson video for S02E01 of the MEGA.dev course, by Angie Jones. Agenda: Agent Loop · Instructions · Context and Memory · Tools. The video plays on the lesson page in MEGA Student HQ (needs a login).
0:05 Congratulations, you're now in charge of your retail company's newly developed customer service agent. We're signed in as Alex, a customer who wants to exchange a pair of shoes for a larger size. Notice, the customer vaguely described what they want, as customers do. And now the agent needs to work out how to respond using its instructions and the capabilities that it has. Of course the agent needs the order number, so let's go ahead and supply that. And now it's able to look up the shoes. Now given the order number, the agent successfully found the order, which is a pair of blue sneakers in a size 8. And it then asked the customer which size that they'd like to replace these with.
So, let's go ahead and say a 9. And then the agent comes back and says that it can't actually check availability or do exchanges. So, why did it ask us that question in the first place? This is the kind of stuff that annoys customers when your company rolls out its fancy new agent. As engineers we can make this better. First, we need to understand why the agent responded this way. So, let's open up its definition and look at the instructions and capabilities that it's been given. The agent is built using the open source framework Mastra, and here's its definition. It needs a model to process the information it's given and generate a response. And this is your first design decision to make.
So, you shouldn't reach for the biggest, most expensive model on the market by default. Remember you have end users that are engaging with this agent. So, ask yourself, given the task that your agent needs to do, what's the most efficient, yet affordable model that you can use? So, we're using GPT-6 Luna here, which is a smaller model because the agent's tasks are fairly focused, right? It just needs to identify some missing information, request a order lookup, and respond using the results. So, smaller models generally cost less and they can respond faster. So, they're a useful starting point for this kind of task. And you can test whether the model follows instructions and uses its tools correctly.
And if it does struggle, then you can try a more capable model. Now let's look at the instructions. Now, the instructions are critical system-level prompts that define the agent's identity and expertise, and we can also use these instructions to guide the agent's behavior. For example, we state that the agent is not allowed to make up details. Instead, we tell it what to do if the tool isn't available. And we also give it permission to fail versus making up order details just to give the customer an answer. Also, we give it permission to ask for missing information. That's why it asked Alex for an order number. The lookup needs that information, so we've told the agent to ask for it rather than to guess.
And then we can also give the agent tools. So, this is what allows the agent to actually take actions. And these can be tools that we've defined and implemented, or they can be external tools. For example, here's where we've registered the getOrder tool with the agent. And this tool maps to a function that we've implemented. Now, registering the tool makes it available to the model along with its description. And that description explains what the tool does and when to use it. Now, notice that getOrder's availability is conditional on the order lookup setting. So, you could use this same approach to make a tool available based on anything, like the customer's permissions or anything else.
And then there's two other tools here that we've created as custom memory helpers. In fact, let's look at memory. So here, we're defining how our agent's memory should work. So, we're supplying earlier messages so that the agent can follow the conversation. When Alex replies with just an order number, those earlier messages explain what Alex was even talking about. Here we include the latest 20 messages from this thread. And we could send the entire conversation, but the model processes that history with every request, right? So, as the conversation grows, that means more tokens to pay for, and potentially slower responses. Models also have a limit on how much information they can receive in one call.
So, keeping the last 20 messages puts a bound on how much history that we're sending. But there is a trade-off, right? An important detail from earlier in the conversation might get left out. And 20 isn't a magic number. We needed to choose a limit that gives our agent enough history to handle the customer's request without sending more than what it needs. Now, one fascinating thing about memory is that there are several different types of memory and all of them work a bit differently. For example, semantic recall would retrieve relevant messages based on their meaning rather than exact keywords. We've turned that off so that we're using recent messages without that extra search.
5:07 And then working memory lets the agent keep information across conversations. So, we've turned this off as well, because we don't want the agent automatically carrying order details into its next request. Now, we still want customers to be able to save shopping preferences, and for that we've registered read preference and save preference tools. So, the agent can save a preference when the customer asks it to remember one, and then it can retrieve a preference in another conversation. So, buying a pair of shoes or requesting a replacement size doesn't, by itself, ask the agent to save a preference. Now, all of these configurations together shape how the agent responds. And it also gives us a hint of which parts of the agent we might need to observe and tweak when its behavior is not ideal.
Now, remember we saw the agent ask Alex for more information even though it couldn't complete the exchange. The instructions that we've given it shaped that behavior. If we're telling it to collect replacement details, then we need to consider whether collecting those details is useful with the tools that it currently has. Or maybe we can even extend its capabilities by providing more tools. So, that's why we're looking at how this agent is configured. We want to understand what's leading it to ask those questions so that we can decide what needs to change. In this case, we can already see why it's asking for replacement details. We've instructed it to do that, even though it can't complete the exchange.
But when you're working on an agent, it might not always be that obvious, right? You might get an incorrect answer, and you need to find out whether the tool returned the wrong information or the model used that information incorrectly. So, let's use this request to learn how to inspect what happened during a run, and we'll follow the order lookup and see how the result became a part of the agent's answer. So, many people treat agents as black boxes. But, as engineers, we need to know how to peek inside that box and what to look for. So, let's check the trace in Mastra Studio. A trace is a record of what the agent did during one run.
We can use it to check whether the agent called the right tool and whether that tool returned the information that it needed. So, here's the run from when Alex supplied the order number. In the trace details, we can follow the steps that the agent took to answer Alex. So, this trace shows what happened during the run. The conversation history is loaded from memory, then the model works through its steps, calling tools as needed, and then finally the conversation is saved for the next message. The numbering starts at zero. So, step zero is the first step. Now, under input, we have our instructions from our agent definition. That's going to be in every single step, which is why I said whatever is in those instructions is critical.
And then the input also includes the recent conversation history up to 20 messages, which we configured in the memory setting. Okay, now let's take a look at the output. So, the model has made a tool request, and it wants the agent to run the getOrder tool and it supplied Alex's order number as the argument. The agent then runs that function, which we can inspect in a separate getOrder entry in the trace. So, input shows what the function received and output shows what it returned. So here, the lookup found Alex's order and returned the blue sneaker in size 8. Now, the database access happens in our code. We don't need the model to figure out how to query the database or decide whether Alex is allowed to access this order.
We've already defined those rules, so we can enforce them with deterministic code. And that gives us a predictable check without paying for another model call or waiting for its response. And then it also helps with debugging. So, if the agent gave Alex the wrong shoe size, then this is one place that we would look. If the value was wrong in the tool result, we'd check the lookup code or the stored order, right? But if the value was correct here, and then wrong in the agent's answer, then we'd investigate how the agent used that result. Let's look at the next step. So, along with the conversation, there is also now a result from the call to getOrder.
So, the agent sent that result back to the model for another call, giving it information that it didn't have in the first step. And this cycle, where the agent repeatedly presents the model with information, and then the model responds to the agent with the next action to take, this is what's known as the agentic loop. So, when the model requests a tool, the agent runs it and sends the result back. And then the model can then use that result to respond or request another tool.
10:11 And note that finishing a run doesn't mean that the customer's problem is solved. In Alex's case, the model responded with a question, right? So, this run ended and the agent waited for another customer message. As you're developing your agents, one important thing to consider is how many times the model can continue this loop. So, if a tool keeps returning an error for example, we don't want the agent to keep trying indefinitely while the customer waits and we pay for more calls. So, we can set a limit on how many model steps a run can take. So, here in our agent definition, we've added a default option that sets maxSteps to 5, which gives each run a limit of five model steps.
A step is a call to the model and that call can request more than one tool. So, five steps doesn't mean five tool calls. It means the model can be called up to five times during that run. It's also a maximum, not a target, right? So, the agent can respond before it reaches that limit, which would be great. So, how do you choose a suitable limit for your agent? Well, you'll need to test the work that the agent needs to do. So, you can run multiple scenarios via evals, which we'll cover in detail in a later chapter in this course. And we could measure how many steps it takes an agent to get to a successful result without excessive floundering, right?
So, our agent needed two steps, so five gives it a bit of buffer. Now back to the agent's annoying behavior, where it's quizzing the user for exchange details even though it has no capability to process exchanges. We now know where to go to fix this. So, let's do that. Here in the instructions is where we're telling the agent to collect replacement details, and we also tell it that it can't process exchanges. So, we've given it instructions to gather information that it can't use. So really, this is our fault. And then people blame it on AI. As engineers, we can change that behavior. For now, we want it to explain that exchanges aren't supported and to stop asking exchange questions, right?
So, it should still help when a customer asks to look up an order. So, let's go ahead and change that and we'll leave everything else the same: the model, the order, and the tools. I'm starting a new thread so that the agent has fresh context. Let's go ahead and ask about the exchange again. Great, that's much better. Models are non-deterministic, but we do have a bit of control. So, the system instructions are included with every call to the model. That means the agent gets that guidance again on every turn. Now, I don't want to mislead you. Instructions don't guarantee that the model will always behave as intended, but at least you've done your part to guide it in the right direction.
The model itself is stateless. It has no recollection of previous calls. So, every time our agent calls the model, it has to supply all of the information that the model needs to respond. And that information is its context. So, the context window is the limit on how much the model can work with at once. The system instructions are a part of that context, and our agent also includes up to the last 20 messages from the conversation, which is inclusive of the user's prompts as well as the model's responses. And it also supplies information about the available tools, such as their names and descriptions along with the arguments that each tool accepts. So, if a tool has already run, then its result is included there as well.
As the conversation grows, we need to decide what to keep sending, right? Remember that we've limited the message history to 20 messages, and some of the older messages before then may still be relevant. Some of it may not. So, compaction is helpful here. It's where older messages are compressed into shorter notes that are included with recent messages. The trade-off is that those notes may leave out some details. We can also save specific information separately from the conversation. Our agent can retrieve a preference, for example, when it's needed and include it in the model's context. Let's see how that works. So, let's first ask whether the agent has a saved shoe size for Alex. So, we see that it calls the read preference tool, which is a tool that we implemented to read this information from the store.
The result says that it wasn't found, which is exactly what we expect because we have not saved this preference yet. So, let's go ahead and store it. "Please remember my preferred shoe size is 9." This time, the model calls the save preference tool, which writes that preference to the database and returns a confirmation. Okay, let's try again in a new thread. Wonderful. So, we know that our agent is capable of remembering and recalling things outside of a chat session.
15:13 But there's a bit more to consider here, right? When you add memory to an agent, decide what's worth remembering. Let's look at the functions for these tools. Now, we're making a deliberate choice about what should carry across conversations. A customer might discuss one order today and a different order tomorrow, and we don't want a remembered order number deciding which purchase their next request is about. Remember that we've disabled automatic working memory in the agent definition, and instead we provided those tools specifically for shopping preferences. The save tool's schema accepts categories such as shoe size and shirt size, and the tool description tells the model to save only when the customer asks it to remember a preference.
And our agent pulls the customer's identity when it reads or writes a preference. And the database stores each category separately for each customer. So, another customer's lookup doesn't return Alex's preferences, for example. Let's dive a bit more into the power of tools. Here in our agent definition, we've seen the agent retrieve order details using getOrder. Now I want to show you what happens if we remove that tool and how the agent responds when it can no longer look up the order. Now, remember that getOrder is conditionally available and this order lookup setting controls whether it's included in the tools that we give the model. So, I'm going to change it to false. And now, if we look in Studio, we see that getOrder is no longer available to the agent.
In a new thread, let's ask it about an order. So, the agent sent the model the system instructions, the user's prompt, and info about the tools that it had access to, which are only the read and save preferences tool. The model doesn't have access to the database, right? And it only has access to whatever information the agent has provided to it. So, when we remove this tool from the agent, it no longer has access to that tool, so it can't share that with the model. So, tools are what agents use to take actions. I'm going to revert this back to true and then let's inspect the tool definition. So, the description says, "Retrieve an order belonging to the current customer."
And that tells the model what the tool does. The next sentence says that it should use it to verify order details before answering questions about a purchase, and that tells the model when to use it. So, we've kept that guidance with the tool rather than repeating it in the agent's instructions. And the instructions still say not to invent order details and what to do when lookup isn't available. We need those rules even when this tool isn't registered. Now, the input schema defines the input that the tool accepts, which in this case is an order ID. And the execute function contains the application code that performs the lookup. So, those parts have different jobs. A clear description helps the model select the appropriate tool, a schema lets the application validate the shape of the request, and then the implementation determines what actually happens.
Now, an order ID being a valid string doesn't mean that the customer is allowed to see that order. So, we also need to check access in the implementation as well. Here's where we enforce access. The query requires both the requested order ID and the current customer's ID to match. So, this is common sense programming, but let's face it, you know, many of us aren't coding much anymore. So, I just want to point out how important it is for us to remember the logic even if we're not the ones that's writing the code. So, if Alex supplies someone else's order number, that combination won't match and the function returns order not found for this customer without returning the other customer's order's details.
So, the model can request the lookup, but our code controls which record it can retrieve. And that access check runs every time the tool performs a lookup. So, we aren't relying on the model to follow some instructions about privacy. So, one more thing before we wrap up this chapter. I want to touch on how we test this agent with evals. So, evals are tests where we give the agent a request, and then we check its behavior against what we expect. And these cases use our customer Alex and orders that we've created as test data. Because we know what's in those orders, we can check whether the agent retrieves and reports the correct information. For a production agent, we'd expand this set to cover different customers and different situations.
Okay, each case describes the behavior that we want rather than requiring one exact sentence, for example. So, for a direct order question, we check that the agent calls getOrder and reports the correct purchased item. A plausible answer isn't enough, we want to see that it used the store's data.
20:14 For an exchange request, we check that the agent explains its limitations without collecting more details or claiming that an exchange has been approved. So, this checks whether the instruction change we made actually stops that unnecessary behavior. And then when querying another customer's order, we check that the lookup returns no accessible order and that the answer doesn't disclose its contents. So, this checks both the access rule in our code and how the agent responds when access is denied. So, just like any application tests, it's a good idea to rerun these cases after changing the agent's instructions, or its tools, or its model to check whether a change broke anything that was working before. In this chapter, we explored the primitives that make up an agent and how the model, the system instructions, the tools, context, and memory all come together within the agentic loop.
As engineers, we decide how to configure these pieces. And we can inspect their behavior and tweak these configurations to have the agent work as we intended. In the next chapter, we'll build on this retail agent and we'll start giving it some capabilities to actually handle an exchange and introduce a decision model to help it decide what to do next.