Agent class

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

Usage examples

Basic string instructions

Passing instructions as a string or array of strings is the simplest way to set up an agent. This is useful for straightforward use cases where you just need to provide a prompt without additional configuration.

import { Agent } from '@mastra/core/agent'

// String instructions
export const agent = new Agent({
  id: 'test-agent',
  name: 'Test Agent',
  // highlight-next-line
  instructions: 'You are a helpful assistant that provides concise answers.',
  model: 'openai/gpt-5.4',
})

// System message object
export const agent2 = new Agent({
  id: 'test-agent-2',
  name: 'Test Agent 2',
  // highlight-start
  instructions: {
    role: 'system',
    content: 'You are an expert programmer',
  },
  // highlight-end
  model: 'openai/gpt-5.4',
})

// Array of system messages
export const agent3 = new Agent({
  id: 'test-agent-3',
  name: 'Test Agent 3',
  // highlight-start
  instructions: [
    { role: 'system', content: 'You are a helpful assistant' },
    { role: 'system', content: 'You have expertise in TypeScript' },
  ],
  // highlight-end
  model: 'openai/gpt-5.4',
})

Provider-specific configurations

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

import { Agent } from '@mastra/core/agent'

export const agent = new Agent({
  id: 'core-message-agent',
  name: 'Core Message Agent',
  instructions: {
    role: 'system',
    content: 'You are a helpful assistant specialized in technical documentation.',
    // highlight-start
    providerOptions: {
      openai: {
        reasoningEffort: 'low',
      },
    },
    // highlight-end
  },
  model: 'openai/gpt-5.4',
})

Mixed instruction formats

import { Agent } from '@mastra/core/agent'

// This could be customizable based on the user
const preferredTone = {
  role: 'system',
  content: 'Always maintain a professional and empathetic tone.',
}

export const agent = new Agent({
  id: 'multi-message-agent',
  name: 'Multi Message Agent',
  instructions: [
    { role: 'system', content: 'You are a customer service representative.' },
    preferredTone,
    {
      role: 'system',
      content: 'Escalate complex issues to human agents when needed.',
      providerOptions: {
        anthropic: { cacheControl: { type: 'ephemeral' } },
      },
    },
  ],
  model: 'anthropic/claude-sonnet-4-6',
})

Constructor parameters

<PropertiesTable content={[ { name: 'id', type: 'string', isOptional: true, description: 'Unique identifier for the agent. Defaults to name if not provided.', }, { name: 'name', type: 'string', isOptional: false, description: 'Display name for the agent. Used as the identifier if id is not provided.', }, { name: 'description', type: 'string', isOptional: true, description: "Optional description of the agent's purpose and capabilities.", }, { name: 'instructions', type: 'SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise', isOptional: false, description: Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, array of system messages, or a function that returns any of these types dynamically. SystemMessage types: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[], }, { name: 'model', type: 'MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>', isOptional: false, description: 'The language model used by the agent. Can be provided statically or resolved at runtime.', }, { name: 'agents', type: 'Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>', isOptional: true, description: 'Subagents that the agent can access. Can be provided statically or resolved dynamically.', }, { name: 'tools', type: 'ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>', isOptional: true, description: 'Tools that the agent can access. Can be provided statically or resolved dynamically.', }, { name: 'workflows', type: 'Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>', isOptional: true, description: 'Workflows that the agent can execute. Can be static or dynamically resolved.', }, { name: 'defaultOptions', type: 'AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>', isOptional: true, description: 'Default options used when calling stream() and generate().', }, { name: 'defaultGenerateOptionsLegacy', type: 'AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>', isOptional: true, description: 'Default options used when calling generateLegacy().', }, { name: 'defaultStreamOptionsLegacy', type: 'AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>', isOptional: true, description: 'Default options used when calling streamLegacy().', }, { name: 'mastra', type: 'Mastra', isOptional: true, description: 'Reference to the Mastra runtime instance (injected automatically).', }, { name: 'scorers', type: 'MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>', isOptional: true, description: 'Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.', }, { name: 'memory', type: 'MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>', isOptional: true, description: 'Memory module used for storing and retrieving stateful context.', }, { name: 'voice', type: 'CompositeVoice', isOptional: true, description: 'Voice settings for speech input and output.', }, { name: 'inputProcessors', type: '(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>', isOptional: true, description: 'Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with createWorkflow() using ProcessorStepSchema.', }, { name: 'outputProcessors', type: '(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>', isOptional: true, description: 'Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.', }, { name: 'maxProcessorRetries', type: 'number', isOptional: true, description: 'Maximum number of times a processor can request retrying the LLM step.', }, { name: 'requestContextSchema', type: 'z.ZodType<any>', isOptional: true, description: 'Zod schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.', }, ]} />

Returns

<PropertiesTable content={[ { name: 'agent', type: 'Agent<TAgentId, TTools>', description: 'A new Agent instance with the specified configuration.', }, ]} />