Using Agents

Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or agent networks.

📹 Watch: → An introduction to agents, and how they compare to workflows YouTube (7 minutes) 

Setting up agents

npm install @mastra/core

OPENAI_API_KEY=<your-api-key>

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"
});

npm install @mastra/core @ai-sdk/openai

OPENAI_API_KEY=<your-api-key>

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. The examples below illustrate the supported shapes:

// String (most common)
instructions: "You are a helpful assistant."
 
// 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." }
]

Provider-specific options

Each model provider also enables a few different options, including prompt caching and configuring reasoning. We provide a providerOptions flag to manage these. You can set providerOptions on the instruction level to set different caching strategy per system instruction/prompt.

// 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: { reasoningEffort: "high" },        // OpenAI's reasoning models
    anthropic: { cacheControl: { type: "ephemeral" } }  // Anthropic's prompt caching
  }
}

See the Agent reference doc 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

Agents can return results in two ways: generating the full output before returning it or streaming tokens in real time. Choose the approach that fits your use case: generate for short, internal responses or debugging, and stream to deliver pixels to end users as quickly as possible.

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);

const stream = await testAgent.stream([
  { 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" }
]);
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

const stream = await testAgent.stream("Help me organize my day", {
  onFinish: ({ steps, text, finishReason, usage }) => {
    console.log({ steps, text, finishReason, usage });
  }
});
 
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

See .generate() or .stream() for more information.

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"
    }
  ],
  {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        keywords: z.array(z.string())
      })
    },
  }
);
 
console.log(response.object);

With Tool Calling

Use the model property to ensure that your agent can execute multi-step LLM calls with tool calling.

import { z } from "zod";
 
const response = await testAgentWithTools.generate(
  [
    {
      role: "system",
      content: "Provide a summary and keywords for the following text:"
    },
    {
      role: "user",
      content: "Please use your test tool and let me know the results"
    }
  ],
  {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        keywords: z.array(z.string())
      }),
      model: "openai/gpt-4o"
    },
  }
);
 
console.log(response.object);
console.log(response.toolResults)

Response format

By default structuredOutput will use response_format to pass the schema to the model provider. If the model provider does not natively support response_format it’s possible that this will error or not give the desired results. To keep using the same model use jsonPromptInjection to bypass response format and inject a system prompt message to coerce the model to return structured output.

import { z } from "zod";
 
const response = await testAgentThatDoesntSupportStructuredOutput.generate(
  [
    {
      role: "system",
      content: "Provide a summary and keywords for the following text:"
    },
    {
      role: "user",
      content: "Monkey, Ice Cream, Boat"
    }
  ],
  {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        keywords: z.array(z.string())
      }),
      jsonPromptInjection: true
    },
  }
);
 
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);

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 });
  }
});

Using tools

Agents can use tools to go beyond language generation, enabling structured interactions with external APIs and services. Tools allow agents to access data and perform clearly defined operations in a reliable, repeatable way.

export const testAgent = new Agent({
  // ...
  tools: { testTool }
});

See Using Tools for more information.

Using RuntimeContext

Use RuntimeContext to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.

export type UserTier = {
  "user-tier": "enterprise" | "pro";
};
 
export const testAgent = new Agent({
  // ...
  model: ({ runtimeContext }) => {
    const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
 
    return userTier === "enterprise"
      ? openai("gpt-4o-mini")
      : openai("gpt-4.1-nano");
  }
});

See Runtime Context for more information.

Testing with Mastra Playground

Use the Mastra Playground to test agents with different messages, inspect tool calls and responses, and debug agent behavior.

Related

• Using Tools
• Agent Memory
• Runtime Context
• Calling Agents