Skip to main content

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​

src/mastra/agents/string-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

// String instructions
export const agent = new Agent({
  name: "test-agent",
  instructions: "You are a helpful assistant that provides concise answers.",
  model: openai("gpt-4o"),
});

// System message object
export const agent2 = new Agent({
  name: "test-agent-2",
  instructions: {
    role: "system",
    content: "You are an expert programmer",
  },
  model: openai("gpt-4o"),
});

// Array of system messages
export const agent3 = new Agent({
  name: "test-agent-3",
  instructions: [
    { role: "system", content: "You are a helpful assistant" },
    { role: "system", content: "You have expertise in TypeScript" },
  ],
  model: openai("gpt-4o"),
});

Single CoreSystemMessage​

Use CoreSystemMessage format to access additional properties like providerOptions for provider-specific configurations:

src/mastra/agents/core-message-agent.ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";

export const agent = new 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"),
});

Multiple CoreSystemMessages​

src/mastra/agents/multi-message-agent.ts
import { anthropic } from "@ai-sdk/anthropic";
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({
  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-20250514"),
});

Constructor parameters​

id?:

string
Optional unique identifier for the agent. Defaults to `name` if not provided.

name:

string
Unique identifier for the agent.

description?:

string
Optional description of the agent's purpose and capabilities.

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>>
Sub-Agents 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.

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.

defaultGenerateOptions?:

AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>
Default options used when calling `generate()`.

defaultStreamOptions?:

AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>
Default options used when calling `stream()`.

defaultStreamOptions?:

AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>
Default options used when calling `stream()` in vNext mode.

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.

evals?:

Record<string, Metric>
Evaluation metrics for scoring agent responses.

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[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>
Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.

outputProcessors?:

Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>
Output processors that can modify or validate messages from the agent, before it is sent to the client. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.

Returns​

agent:

Agent<TAgentId, TTools, TMetrics>
A new Agent instance with the specified configuration.