Using Agents
Agents let you build intelligent assistants powered by language models that can make decisions and perform actions. Each agent has required instructions and an LLM, with optional tools and memory.
An agent coordinates conversations, calls tools when needed, maintains context through memory, and produces responses tailored to the interaction. Agents can operate on their own or work as part of larger workflows.
To create an agent:
- Define instructions with the
Agent
class and set the LLM it will use. - Optionally configure tools and memory to extend functionality.
- Run the agent to generate responses, with support for streaming, structured output, and dynamic configuration.
This approach provides type safety and runtime validation, ensuring reliable behavior across all agent interactions.
📹 Watch: → An introduction to agents, and how they compare to workflows YouTube (7 minutes)Â
Getting started
To use agents, install the required dependencies:
npm install @mastra/core @ai-sdk/openai
Mastra works with all AI SDK provider. See Model Providers for more information.
Import the necessary class from the agents module, and an LLM provider:
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
LLM providers
Each LLM provider needs its own API key, named using the provider’s identifier:
OPENAI_API_KEY=<your-api-key>
See the AI SDK Providers in the Vercel AI SDK docs.
Creating an agent
To create an agent in Mastra, use the Agent
class. Every agent must include instructions
to define its behavior, and a model
parameter to specify the LLM provider and model:
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
export const testAgent = new Agent({
name: "test-agent",
instructions: "You are a helpful assistant.",
model: openai("gpt-4o-mini")
});
Instruction formats
Instructions define the agent’s behavior, personality, and capabilities. They are system-level prompts that establish the agent’s core identity and expertise.
Instructions can be provided in multiple formats for greater flexibility:
// String (most common)
instructions: "You are a helpful assistant."
// System message object
instructions: {
role: "system",
content: "You are an expert programmer."
}
// Array of strings
instructions: [
"You are a helpful assistant.",
"Always be polite.",
"Provide detailed answers."
]
// Array of system messages
instructions: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "system", content: "You have expertise in TypeScript." }
]
// With provider-specific options (e.g., caching, reasoning)
instructions: {
role: "system",
content: "You are an expert code reviewer. Analyze code for bugs, performance issues, and best practices.",
providerOptions: {
openai: { reasoning_effort: "high" }, // OpenAI's reasoning models
anthropic: { cache_control: { type: "ephemeral" } } // Anthropic's prompt caching
}
}
Provider-specific options allow you to leverage unique features of different LLM providers:
- Anthropic caching: Reduce costs by caching frequently-used instructions
- OpenAI reasoning: Enable deeper analysis for complex tasks
- Custom parameters: Pass any provider-specific configuration
See Agent for more information.
Registering an agent
Register your agent in the Mastra instance to make it available throughout your application. Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features:
import { Mastra } from "@mastra/core/mastra";
import { testAgent } from './agents/test-agent';
export const mastra = new Mastra({
// ...
agents: { testAgent },
});
Referencing an agent
You can call agents from workflow steps, tools, the Mastra Client, or the command line. Get a reference by calling .getAgent()
on your mastra
or mastraClient
instance, depending on your setup:
const testAgent = mastra.getAgent("testAgent");
See Calling agents for more information.
Generating responses
Use .generate()
to get a response from an agent. Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with role
and content
for precise control over roles and conversational flows.
See .generate() for more information.
Generating text
Call .generate()
with an array of message objects containing role
and content
. The role
defines the speaker for each message. Typical roles are user
for human input, assistant
for agent responses, and system
for instructions. This structure helps the LLM maintain conversation flow and generate contextually appropriate responses.
const response = await testAgent.generate([
{ role: "user", content: "Help me organize my day" },
{ role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
{ role: "user", content: "I take lunch between 12:30 and 13:30" },
{ role: "user", content: "I have meetings Monday to Friday between 10:30 and 11:30" }
]);
console.log(response.text);
Structured output
Agents can return structured, type-safe data by defining the expected output using either Zod or JSON Schema . We recommend Zod for better TypeScript support and developer experience. The parsed result is available on response.object
, allowing you to work directly with validated and typed data.
Using Zod
Define the output
shape using Zod :
import { z } from "zod";
const response = await testAgent.generate(
[
{
role: "system",
content: "Provide a summary and keywords for the following text:"
},
{
role: "user",
content: "Monkey, Ice Cream, Boat"
}
],
{
output: z.object({
summary: z.string(),
keywords: z.array(z.string())
})
}
);
console.log(response.object);
Agents with tools
To generate structured output with agents that use tools, use the output
property:
import { z } from "zod";
const response = await testAgent.generate(
// ...
{
output: z.object({
summary: z.string(),
keywords: z.array(z.string())
})
}
);
console.log(response.object);
Working with images
Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with type: 'image'
and the image URL in the content
array. You can combine image content with text prompts to guide the agent’s analysis.
const response = await testAgent.generate([
{
role: "user",
content: [
{
type: "image",
image: "https://placebear.com/cache/395-205.jpg",
mimeType: "image/jpeg"
},
{
type: "text",
text: "Describe the image in detail, and extract all the text in the image."
}
]
}
]);
console.log(response.text);
Multi-step tool use
Agents can be enhanced with tools, functions that extend their capabilities beyond text generation. Tools allow agents to perform calculations, access external systems, and process data. Agents not only decide whether to call tools they’re given, they determine the parameters that should be given to that tool.
For a detailed guide to creating and configuring tools, see the Tools Overview page.
Using maxSteps
The maxSteps
parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 1, but can be increased:
const response = await testAgent.generate("Help me organize my day", {
maxSteps: 5
});
console.log(response.text);
Using onStepFinish
You can monitor the progress of multi-step operations using the onStepFinish
callback. This is useful for debugging or providing progress updates to users.
onStepFinish
is only available when streaming or generating text without structured output.
const response = await testAgent.generate("Help me organize my day", {
onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
console.log({ text, toolCalls, toolResults, finishReason, usage });
}
});
Testing agents locally
There are two ways to run and test agents.
Mastra Playground
With the Mastra Dev Server running you can test an agent from the Mastra Playground by visiting http://localhost:4111/agents in your browser.
For more information, see the Local Dev Playground documentation.
Command line
Create an agent response using .generate()
or .stream()
.
import "dotenv/config";
import { mastra } from "./mastra";
const agent = mastra.getAgent("testAgent");
const response = await agent.generate("Help me organize my day");
console.log(response.text);
See .generate() or .stream() for more information.
To test this agent, run the following:
npx tsx src/test-agent.ts