Agents Overview

Agents in Mastra are systems where the language model can autonomously decide on a sequence of actions to perform tasks. They have access to tools, workflows, and synced data, enabling them to perform complex tasks and interact with external systems. Agents can invoke your custom functions, utilize third-party APIs through integrations, and access knowledge bases you have built.

While the LLM class is similar to a contractor you might hire for a one-off task, agents are like employees who can be used for ongoing projects. They have names, persistent memory, consistent model configurations, and instructions across calls, as well as a set of enabled tools.

1. Creating an Agent

To create an agent in Mastra, you use the Agent class and define its properties:

src/mastra/agents/index.ts

import { Agent } from "@mastra/core";
 
export const myAgent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant.",
  model: {
    provider: "OPEN_AI",
    name: "gpt-4o-mini",
  },
});

Note: Ensure that you have set the necessary environment variables, such as your OpenAI API key, in your .env file:

.env

OPENAI_API_KEY=your_openai_api_key

Also, make sure you have the @mastra/core package installed:

npm install @mastra/core

pnpm add @mastra/core

yarn add @mastra/core

bun add @mastra/core

Registering the Agent

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { myAgent } from "./agents";
 
export const mastra = new Mastra({
  agents: { myAgent },
});

2. Generating and streaming text

Generating text

Use the .generate() method to have your agent produce text responses:

src/mastra/index.ts

const response = await myAgent.generate([
  { role: "user", content: "Hello, how can you assist me today?" },
]);
 
console.log("Agent:", response.text);

Streaming responses

For more real-time responses, you can stream the agent’s response:

src/mastra/index.ts

const stream = await myAgent.stream([
  { role: "user", content: "Tell me a story." },
]);
 
console.log("Agent:");
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

3. Structured Output

Agents can return structured data by providing a JSON Schema or using a Zod schema.

Using JSON Schema

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    keywords: { type: "array", items: { type: "string" } },
  },
  additionalProperties: false,
  required: ["summary", "keywords"],
};
 
const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "Please provide a summary and keywords for the following text: ...",
    },
  ],
  {
    output: schema,
  }
);
 
console.log("Structured Output:", response.object);

Using Zod

You can also use Zod schemas for type-safe structured outputs.

First, install Zod:

npm install zod

pnpm add zod

yarn add zod

bun add zod

Then, define a Zod schema and use it with the agent:

src/mastra/index.ts

import { z } from "zod";
 
// Define the Zod schema
const schema = z.object({
  summary: z.string(),
  keywords: z.array(z.string()),
});
 
// Use the schema with the agent
const response = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "Please provide a summary and keywords for the following text: ...",
    },
  ],
  {
    output: schema,
  }
);
 
console.log("Structured Output:", response.object);

This allows you to have strong typing and validation for the structured data returned by the agent.

4. Running Agents

Mastra provides a CLI command mastra dev to run your agents behind an API. By default, this looks for exported agents in files in the src/mastra/agents directory.

Starting the Server

mastra dev

This will start the server and make your agent available at http://localhost:4111/api/agents/myAgent/generate.

Interacting with the Agent

You can interact with the agent using curl from the command line:

curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, how can you assist me today?" }
    ]
  }'

Next Steps

Learn about Agent Memory in the Agent Memory guide.
Learn about Agent Tools in the Agent Tools guide.
See an example agent in the Chef Michel example.

Overview Memory