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 need to provide a prompt without additional configuration.

src/mastra/agents/string-agent.ts

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

// String instructions
export const agent = new Agent({
  id: 'test-agent',
  name: 'Test Agent',
  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',
  instructions: {
    role: 'system',
    content: 'You are an expert programmer',
  },
  model: 'openai/gpt-5.4',
})

// Array of system messages
export const agent3 = new Agent({
  id: 'test-agent-3',
  name: 'Test Agent 3',
  instructions: [
    { role: 'system', content: 'You are a helpful assistant' },
    { role: 'system', content: 'You have expertise in TypeScript' },
  ],
  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.

src/mastra/agents/core-message-agent.ts

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.',
    providerOptions: {
      openai: {
        reasoningEffort: 'low',
      },
    },
  },
  model: 'openai/gpt-5.4',
})

Mixed instruction formats

src/mastra/agents/multi-message-agent.ts

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',
})

Thread signals

Use Agent signals to send real-time context into a memory thread. Signals are useful when a user adds input while an agent is already streaming, or when another process needs to add structured context to the thread.

A user-message signal represents user input. When the target thread is running, Mastra delivers the signal into the active agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input by default.

src/mastra/signals.ts

const subscription = await agent.subscribeToThread({
  resourceId: 'user-123',
  threadId: 'thread-abc',
})

void (async () => {
  for await (const chunk of subscription.stream) {
    console.log(chunk)
  }
})()

agent.sendSignal(
  { type: 'user-message', contents: 'Use the latest customer note too.' },
  {
    resourceId: 'user-123',
    threadId: 'thread-abc',
    ifIdle: {
      streamOptions: {
        maxSteps: 3,
      },
    },
  },
)

Use a custom signal type for contextual messages that should reach the model as XML-wrapped context instead of normal user input:

agent.sendSignal(
  {
    type: 'system-reminder',
    contents: 'Continue from the previous tool result.',
    attributes: { reminderType: 'tool-result' },
  },
  { resourceId: 'user-123', threadId: 'thread-abc' },
)

sendSignal(signal, options)

Sends a signal to an active run or memory thread.

signal:

{ type: 'user-message' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }

`user-message` signals are treated as user input. Other signal types are wrapped in XML context (with any `attributes`) before the next model call. `providerOptions` is attached to the resulting prompt turn and persisted on the stored signal message.

options.runId?:

string

Run ID to target directly. Use this when you already know the active run ID.

options.resourceId?:

string

Resource ID for the memory thread. Required with `threadId` for thread-targeted signals.

options.threadId?:

string

Thread ID to target. Required with `resourceId` for thread-targeted signals.

options.ifActive.behavior?:

'deliver' | 'persist' | 'discard'

Controls what happens when the target thread is active. Defaults to `deliver`.

options.ifIdle.behavior?:

'wake' | 'persist' | 'discard'

Controls what happens when the target thread is idle. Defaults to `wake`.

options.ifIdle.streamOptions?:

AgentExecutionOptions

Options for the stream that starts when `ifIdle.behavior` is `wake`. Mastra uses the top-level `resourceId` and `threadId` for memory context.

Returns { accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }. persisted is only present for persist behavior and resolves when Mastra finishes writing the signal to memory.

subscribeToThread(options)

Subscribes to raw stream chunks for a memory thread. Use this before calling sendSignal() when you need to render stream output, observe signal echoes, or abort the active run.

options.resourceId?:

string

Resource ID for the memory thread.

options.threadId:

string

Thread ID to subscribe to.

Returns an AgentThreadSubscription object with these members:

stream:

AsyncIterable<AgentChunkType>

Raw agent stream chunks for the subscribed thread.

activeRunId:

() => string | null

Returns the active run ID for the thread, or `null` when no run is active.

abort:

() => boolean

Aborts the active run for the thread. Returns `true` when a run was aborted.

unsubscribe:

() => void

Stops the subscription without aborting the active run.

Constructor parameters

id?:

string

Unique identifier for the agent. Defaults to `name` if not provided.

name:

string

Display name for the agent. Used as the identifier if `id` is not provided.

description?:

string

Optional description of the agent's purpose and capabilities.

metadata?:

Record<string, unknown> | ({ requestContext: RequestContext }) => Record<string, unknown> | Promise<Record<string, unknown>>

Optional metadata for classifying or filtering the agent in clients. Can be a static record or a function that resolves the metadata from the request context.

instructions:

SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>

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[]

model:

MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>

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

agents?:

Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>

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

tools?:

ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>

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

transform?:

ToolPayloadTransformPolicy

Shared policy for transforming tool payloads before display streams or user-visible transcript messages receive them. Use per-tool `transform` on `createTool()` for tool-local rules.

workflows?:

Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>

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

defaultOptions?:

AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>

Default options used when calling `stream()` and `generate()`.

defaultGenerateOptionsLegacy?:

AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>

Default options used when calling `generateLegacy()`.

defaultStreamOptionsLegacy?:

AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>

Default options used when calling `streamLegacy()`.

mastra?:

Mastra

Reference to the Mastra runtime instance (injected automatically).

scorers?:

MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>

Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.

memory?:

MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>

Memory module used for storing and retrieving stateful context.

voice?:

CompositeVoice

Voice settings for speech input and output.

inputProcessors?:

(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>

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.

outputProcessors?:

(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>

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.

maxProcessorRetries?:

number

Maximum number of times a processor can request retrying the LLM step.

requestContextSchema?:

StandardJSONSchemaV1

Standard JSON 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

agent:

Agent<TAgentId, TTools>

A new Agent instance with the specified configuration.