Introduction to Mastra Agents and Project Setup

Welcome to the first lesson of the "Building a Smart Email Assistant with Mastra" course! In this course, you will learn how to use the Mastra framework to build a smart assistant that can help you with email tasks, such as summarizing email threads.

Mastra is a framework designed to make it easy to build, configure, and run AI-powered agents. These agents can perform tasks like summarizing text, answering questions, or even automating workflows. In this lesson, you will take your first steps with Mastra by creating and running a simple agent.

By the end of this lesson, you will:

• Understand what an agent is in Mastra.
• Define and configure your first agent.
• Register the agent within the Mastra framework.
• Run a simple task to make sure everything works.

Let’s get started!

Before we dive in, here are a few quick reminders to help you get started smoothly:

• CodeSignal Environment: On CodeSignal, most libraries you need (including Mastra and OpenAI SDKs) are already installed. This means you can focus on writing and running code without worrying about setup.
• TypeScript Basics: If you are new to TypeScript, don’t worry. We will keep the code simple and explain each part as we go.

Now, let’s learn about agents in Mastra.

In Mastra, an agent is a smart helper that can perform a specific task using AI. Think of an agent as a digital assistant that follows your instructions to get something done.

For example, you might want an agent to:

• Summarize an email thread.
• Answer questions about a document.
• Organize your to-do list.

Each agent has:

• A name (to identify it).
• Instructions (what you want it to do).
• A model (the AI engine it uses, like OpenAI’s GPT-4o).

In this lesson, you will build an agent that summarizes the main points of an email thread.

Let’s look at how your project is structured and how you define your first agent.

You define your agent in its own file. Here’s what the code looks like:

import { Agent } from "@mastra/core/agent";
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
  baseURL: process.env.OPENAI_BASE_URL,
  compatibility: 'strict',
});

export const SummaryAgent = new Agent({
  name: "Email Summarizer",
  instructions: "Summarize the main points of an email thread.",
  model: openai("gpt-4o"),
});

• name: This is what you call your agent. Here, it’s "Email Summarizer."
• instructions: This tells the agent what to do. In this case, it should summarize email threads.
• model: This is the AI model the agent will use. We are using OpenAI’s gpt-4o model, configured with your environment.

You initialize the Mastra framework and register your agent like this:

import { readFileSync } from "fs";
import { join } from "path";
import { Mastra } from "@mastra/core";
import { SummaryAgent } from "./agents/SummaryAgent.js";

// Initialize Mastra framework
const mastra = new Mastra({
  agents: { SummaryAgent },
});

• The Mastra instance is created with your agents included in the agents object. This registers the agent so you can use it later.

You have a sample email stored in a text file at src/mastra/assets/example-email.txt:

From: alice@example.com
To: bob@example.com
Subject: Meeting Reminder

Hi Bob,

Just a reminder about our meeting tomorrow at 10am.

Best,
Alice

You read this file in your code:

const emailContent = readFileSync("example-email.txt", "utf-8");

You can now use your agent to summarize the email:

async function main() {
  const agent = mastra.getAgent("SummaryAgent");
  
  const emailContent = readFileSync("example-email.txt", "utf-8");
  
  const response = await agent.generate([
    { role: "user", content: emailContent }
  ]);
  console.log(response.text);
}

main();

• mastra.getAgent("SummaryAgent") retrieves your registered agent.
• agent.generate([...]) asks the agent to perform its task, passing in the email content as a message.
• console.log(response.text) prints the agent’s summary to the console.

Expected Output:
When you run this code, you should see a summary of the example email thread printed in the console. The exact output will depend on the model and the input, but it should look something like:

Reminder: Meeting scheduled for tomorrow at 10am between Alice and Bob.

In this lesson, you learned:

• What Mastra is and how it helps you build smart assistants.
• What an agent is in Mastra and why it’s useful.
• How to define, configure, and register your first agent in a real project structure.
• How to run a simple task to test your setup using a real email file.

Next, you will get hands-on practice with these steps in the exercises. You’ll have a chance to write your own code, experiment with different instructions, and see how agents respond to different inputs. Let’s move on and start building!