Agent

AI agent class for creating conversational AI systems with tools, memory, and voice capabilities

Overview

The Agent class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, managing memory, and handling voice capabilities.

Type Parameters

TAgentId · string · default: "string"

The unique identifier type for the agent

TTools · ToolsInput · default: "ToolsInput"

The tools available to the agent

TOutput · any · default: "undefined"

The structured output type (when using structured output)

TRequestContext · Record<string, any> · default: "unknown"

The request context schema type

Constructor

new Agent(config: AgentConfig<TAgentId, TTools, TOutput, TRequestContext>)

config · AgentConfig · required

Configuration for the agent

Show properties

id · string · required

Identifier for the agent

name · string · required

Unique identifier for the agent

description · string

Description of the agent’s purpose and capabilities

instructions · AgentInstructions | DynamicArgument<AgentInstructions> · required

Instructions that guide the agent’s behavior. Can be a string, system message object, array of system messages, or a function that returns any of these types dynamically.

model · MastraModelConfig | ModelWithRetries[] · required

The language model used by the agent. Can be provided statically or resolved at runtime.

maxRetries · number · default: "0"

Maximum number of retries for model calls in case of failure

tools · ToolsInput | DynamicArgument<ToolsInput>

Tools that the agent can access. Can be provided statically or resolved dynamically.

workflows · Record<string, Workflow> | DynamicArgument<Record<string, Workflow>>

Workflows that the agent can execute. Can be static or dynamically resolved.

defaultGenerateOptionsLegacy · AgentGenerateOptions | DynamicArgument<AgentGenerateOptions>

Default options used when calling generate()

defaultStreamOptionsLegacy · AgentStreamOptions | DynamicArgument<AgentStreamOptions>

Default options used when calling stream()

defaultOptions · AgentExecutionOptions | DynamicArgument<AgentExecutionOptions>

Default options used when calling stream() or generate() in vNext mode

defaultNetworkOptions · NetworkOptions | DynamicArgument<NetworkOptions>

Default options used when calling network()

mastra · Mastra

Reference to the Mastra runtime instance (injected automatically)

agents · Record<string, Agent> | DynamicArgument<Record<string, Agent>>

Sub-agents that the agent can access. Can be provided statically or resolved dynamically.

scorers · MastraScorers | DynamicArgument<MastraScorers>

Scoring configuration for runtime evaluation and observability

memory · MastraMemory | DynamicArgument<MastraMemory>

Memory module used for storing and retrieving stateful context

skillsFormat · SkillFormat · default: "'xml'"

Format for skill information injection when workspace has skills

voice · MastraVoice

Voice settings for speech input and output

workspace · Workspace | DynamicArgument<Workspace>

Workspace for file storage and code execution. When configured, workspace tools are automatically injected into the agent.

inputProcessors · InputProcessorOrWorkflow[] | DynamicArgument<InputProcessorOrWorkflow[]>

Input processors that can modify or validate messages before they are processed by the agent

outputProcessors · OutputProcessorOrWorkflow[] | DynamicArgument<OutputProcessorOrWorkflow[]>

Output processors that can modify or validate messages from the agent, before it is sent to the client

maxProcessorRetries · number

Maximum number of times processors can trigger a retry per generation. When a processor calls abort({ retry: true }), the agent will retry with feedback.

options · AgentCreateOptions

Options to pass to the agent upon creation

rawConfig · Record<string, unknown>

Raw storage configuration this agent was created from. Set when the agent is hydrated from a stored config.

requestContextSchema · ZodSchema<TRequestContext>

Optional schema for validating request context values. When provided, the request context will be validated against this schema.

Properties

id · string

The unique identifier for the agent

name · string

The name of the agent

source · 'code' | 'stored' | undefined

The source of the agent (code-defined or loaded from storage)

model · MastraModelConfig | ModelFallbacks

The language model configuration for the agent

maxRetries · number | undefined

Maximum number of retries for model calls

voice · MastraVoice

The voice instance for text-to-speech and speech-to-text capabilities

requestContextSchema · ZodSchema | undefined

The Zod schema used to validate request context values

Methods

Core Execution Methods

generate

generate<TOutput>(
  prompt: string,
  options?: AgentExecutionOptions<TOutput>
): Promise<GenerateResult<TOutput>>

Generates a single response from the agent.

prompt · string · required

The input prompt or message

options · AgentExecutionOptions<TOutput>

Execution options including tools, memory, callbacks, etc.

result · GenerateResult<TOutput>

The generated response with text, tool calls, and metadata

stream

stream<TOutput>(
  prompt: string,
  options?: AgentExecutionOptions<TOutput>
): Promise<AgentStreamResult<TOutput>>

Streams responses from the agent in real-time.

prompt · string · required

The input prompt or message

options · AgentExecutionOptions<TOutput>

Execution options including tools, memory, callbacks, etc.

result · AgentStreamResult<TOutput>

Stream object with fullStream, textStream, toolResultStream, and utility methods

Configuration Getters

getInstructions

getInstructions(options?: { requestContext?: RequestContext }): AgentInstructions | Promise<AgentInstructions>

Gets the instructions for this agent, resolving function-based instructions if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic instructions

instructions · AgentInstructions

The agent’s system instructions

getDescription

getDescription(): string

Returns the description of the agent.

description · string

The agent’s description

listTools

listTools(options?: { requestContext?: RequestContext }): TTools | Promise<TTools>

Gets the tools configured for this agent, resolving function-based tools if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic tools

tools · TTools

The agent’s tools

listWorkflows

listWorkflows(options?: { requestContext?: RequestContext }): Promise<Record<string, Workflow>>

Gets the workflows configured for this agent, resolving function-based workflows if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic workflows

workflows · Record<string, Workflow>

The agent’s workflows

listAgents

listAgents(options?: { requestContext?: RequestContext }): Record<string, Agent> | Promise<Record<string, Agent>>

Returns the agents configured for this agent, resolving function-based agents if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic agents

agents · Record<string, Agent>

The sub-agents

listScorers

listScorers(options?: { requestContext?: RequestContext }): Promise<MastraScorers>

Returns the scorers configured for this agent.

options.requestContext · RequestContext

Request context for resolving dynamic scorers

scorers · MastraScorers

The agent’s scorers

Memory Methods

hasOwnMemory

hasOwnMemory(): boolean

Returns whether this agent has its own memory configured.

hasMemory · boolean

true if the agent has memory configured

getMemory

getMemory(options?: { requestContext?: RequestContext }): Promise<MastraMemory | undefined>

Gets the memory instance for this agent, resolving function-based memory if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic memory

memory · MastraMemory | undefined

The agent’s memory instance, or undefined if not configured

Workspace Methods

hasOwnWorkspace

hasOwnWorkspace(): boolean

Checks if this agent has its own workspace configured.

hasWorkspace · boolean

true if the agent has a workspace configured

getWorkspace

getWorkspace(options?: { requestContext?: RequestContext }): Promise<Workspace | undefined>

Gets the workspace instance for this agent, resolving function-based workspace if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic workspace

workspace · Workspace | undefined

The agent’s workspace instance, or undefined if not configured

Processor Methods

listInputProcessors

listInputProcessors(requestContext?: RequestContext): Promise<InputProcessorOrWorkflow[]>

Returns the input processors for this agent, resolving function-based processors if necessary.

requestContext · RequestContext

Request context for resolving dynamic processors

processors · InputProcessorOrWorkflow[]

The agent’s input processors

listOutputProcessors

listOutputProcessors(requestContext?: RequestContext): Promise<OutputProcessorOrWorkflow[]>

Returns the output processors for this agent, resolving function-based processors if necessary.

requestContext · RequestContext

Request context for resolving dynamic processors

processors · OutputProcessorOrWorkflow[]

The agent’s output processors

resolveProcessorById

resolveProcessorById<TId extends string>(
  processorId: TId,
  requestContext?: RequestContext
): Promise<Processor<TId> | null>

Resolves a processor by its ID from both input and output processors.

processorId · string · required

The processor ID to find

requestContext · RequestContext

Request context for resolving dynamic processors

processor · Processor | null

The processor if found, null otherwise

Voice Methods

getVoice

getVoice(options?: { requestContext?: RequestContext }): Promise<MastraVoice>

Gets the voice instance for this agent with tools and instructions configured.

options.requestContext · RequestContext

Request context for resolving dynamic tools/instructions

voice · MastraVoice

The agent’s voice instance

Model Methods

getLLM

getLLM(options?: {
  requestContext?: RequestContext;
  model?: MastraModelConfig;
}): MastraLLM | Promise<MastraLLM>

Gets or creates an LLM instance based on the provided or configured model.

options.requestContext · RequestContext

Request context for resolving dynamic model

options.model · MastraModelConfig

Optional custom model to use instead of the agent’s model

llm · MastraLLM

The LLM instance

getModel

getModel(options?: {
  requestContext?: RequestContext;
  modelConfig?: MastraModelConfig;
}): MastraLanguageModel | Promise<MastraLanguageModel>

Resolves a model configuration to a LanguageModel instance.

options.requestContext · RequestContext

Request context for resolving dynamic model

options.modelConfig · MastraModelConfig

Optional custom model configuration

model · MastraLanguageModel

The resolved language model instance

Default Options Getters

getDefaultOptions

getDefaultOptions(options?: { requestContext?: RequestContext }): AgentExecutionOptions<TOutput> | Promise<AgentExecutionOptions<TOutput>>

Gets the default options for this agent, resolving function-based options if necessary.

options.requestContext · RequestContext

Request context for resolving dynamic options

options · AgentExecutionOptions<TOutput>

The default execution options

getDefaultNetworkOptions

getDefaultNetworkOptions(options?: { requestContext?: RequestContext }): NetworkOptions | Promise<NetworkOptions>

Gets the default NetworkOptions for this agent.

options.requestContext · RequestContext

Request context for resolving dynamic options

options · NetworkOptions

The default network options containing maxSteps, completion (CompletionConfig), and other network settings

Internal Methods

getMastraInstance

getMastraInstance(): Mastra | undefined

Gets the Mastra instance this agent is registered with.

mastra · Mastra | undefined

The Mastra instance, or undefined if not registered

Example

import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get weather for a location',
  inputSchema: z.object({
    location: z.string()
  }),
  execute: async ({ location }) => {
    return { temperature: 72, conditions: 'sunny' };
  }
});

const agent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  description: 'An agent that provides weather information',
  instructions: 'You are a helpful weather assistant. Provide weather information when asked.',
  model: 'openai/gpt-5',
  tools: {
    getWeather: weatherTool
  },
  memory: new Memory({
    name: 'weather-memory'
  }),
  maxRetries: 2
});

// Generate a response
const response = await agent.generate('What is the weather in New York?');
console.log(response.text);

// Stream a response
const stream = await agent.stream('Tell me about the weather patterns');
for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}