# Agent Class
[EN] Source: https://mastra.ai/reference/agents/agent

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

```typescript title="src/mastra/agents/string-agent.ts" showLineNumbers copy
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:

```typescript title="src/mastra/agents/core-message-agent.ts" showLineNumbers copy
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

```typescript title="src/mastra/agents/multi-message-agent.ts" showLineNumbers copy
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

<PropertiesTable
  content={[
    {
      name: "id",
      type: "string",
      isOptional: true,
      description:
        "Optional unique identifier for the agent. Defaults to `name` if not provided.",
    },
    {
      name: "name",
      type: "string",
      isOptional: false,
      description: "Unique identifier for the agent.",
    },
    {
      name: "description",
      type: "string",
      isOptional: true,
      description:
        "Optional description of the agent's purpose and capabilities.",
    },
    {
      name: "instructions",
      type: "SystemMessage | ({ runtimeContext: RuntimeContext }) => SystemMessage | Promise<SystemMessage>",
      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 | ({ runtimeContext: RuntimeContext }) => 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> | ({ runtimeContext: RuntimeContext }) => Record<string, Agent> | Promise<Record<string, Agent>>",
      isOptional: true,
      description:
        "Sub-Agents that the agent can access. Can be provided statically or resolved dynamically.",
    },
    {
      name: "tools",
      type: "ToolsInput | ({ runtimeContext: RuntimeContext }) => 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> | ({ runtimeContext: RuntimeContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>",
      isOptional: true,
      description:
        "Workflows that the agent can execute. Can be static or dynamically resolved.",
    },
    {
      name: "defaultGenerateOptions",
      type: "AgentGenerateOptions | ({ runtimeContext: RuntimeContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>",
      isOptional: true,
      description: "Default options used when calling `generate()`.",
    },
    {
      name: "defaultStreamOptions",
      type: "AgentStreamOptions | ({ runtimeContext: RuntimeContext }) => AgentStreamOptions | Promise<AgentStreamOptions>",
      isOptional: true,
      description: "Default options used when calling `stream()`.",
    },
    {
      name: "defaultStreamOptions",
      type: "AgentExecutionOptions | ({ runtimeContext: RuntimeContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>",
      isOptional: true,
      description:
        "Default options used when calling `stream()` in vNext mode.",
    },
    {
      name: "mastra",
      type: "Mastra",
      isOptional: true,
      description:
        "Reference to the Mastra runtime instance (injected automatically).",
    },
    {
      name: "scorers",
      type: "MastraScorers | ({ runtimeContext: RuntimeContext }) => MastraScorers | Promise<MastraScorers>",
      isOptional: true,
      description:
        "Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.",
    },
    {
      name: "evals",
      type: "Record<string, Metric>",
      isOptional: true,
      description: "Evaluation metrics for scoring agent responses.",
    },
    {
      name: "memory",
      type: "MastraMemory | ({ runtimeContext: RuntimeContext }) => 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[] | ({ runtimeContext: RuntimeContext }) => Processor[] | Promise<Processor[]>",
      isOptional: true,
      description:
        "Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
    },
    {
      name: "outputProcessors",
      type: "Processor[] | ({ runtimeContext: RuntimeContext }) => Processor[] | Promise<Processor[]>",
      isOptional: true,
      description:
        "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

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

## Related

- [Agents overview](/docs/agents/overview)
- [Calling Agents](/examples/agents/calling-agents)


---
title: "Reference: Agent.generate() | Agents"
description: "Documentation for the `Agent.generate()` method in Mastra agents, which enables non-streaming generation of responses with enhanced capabilities."
---