Agent Options

Configuration options for agent execution (generate and stream methods)

Overview

Agent execution options control how agents process and respond to prompts. These options can be passed to agent.generate() and agent.stream() methods.

AgentExecutionOptions

Base execution options used by both generate() and stream() methods in v2+ mode.

Type Parameters

TOutput · any · default: "undefined"

The structured output type (when using structured output)

Properties

instructions · SystemMessage

Optional instructions to override the agent’s default instructions

toolsets · Record<string, ToolsInput>

Additional tool sets that can be used for this execution

clientTools · ToolsInput

Client-side tools for user confirmation workflows

context · CoreMessage[]

Additional context messages to include

memory · AgentMemoryOption

Memory options for this execution

Show properties

thread · string | (Partial<StorageThreadType> & { id: string }) · required

Thread ID or thread object

resource · string · required

Resource ID for multi-tenant scenarios

options · MemoryConfig

Memory configuration options

runId · string

Unique ID for this execution run

maxSteps · number

Maximum number of steps allowed for execution

toolChoice · 'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

Controls how tools are selected during execution

requestContext · RequestContext

RequestContext for dependency injection

scorers · MastraScorers | Record<string, { scorer: string; sampling?: ScoringSamplingConfig }>

Scorers to use for this execution

returnScorerData · boolean · default: "false"

Whether to return the input required to run scorers for agents

savePerStep · boolean · default: "false"

Whether to save messages incrementally on step finish

inputProcessors · InputProcessorOrWorkflow[]

Input processors to use for this execution (overrides agent’s default)

outputProcessors · OutputProcessorOrWorkflow[]

Output processors to use for this execution (overrides agent’s default)

maxProcessorRetries · number

Maximum number of times processors can trigger a retry. Overrides agent’s default maxProcessorRetries.

tracingOptions · TracingOptions

Tracing options for starting new traces

providerOptions · ProviderOptions

Provider-specific options for supported AI SDK packages (Anthropic, Google, OpenAI, xAI)

structuredOutput · StructuredOutputOptions<TOutput>

Configuration for structured output generation

Show properties

schema · OutputSchema<TOutput> · required

Zod schema to validate the output against

model · MastraModelConfig

Model to use for the internal structuring agent. If not provided, falls back to the agent’s model.

instructions · string

Custom instructions for the structuring agent. If not provided, will generate instructions based on the schema.

jsonPromptInjection · boolean

Whether to use system prompt injection instead of native response format to coerce the LLM to respond with json text if the LLM does not natively support structured outputs.

errorStrategy · 'strict' | 'warn' | 'fallback'

How to handle errors during structured output generation

fallbackValue · TOutput

Fallback value when errorStrategy is ‘fallback’

providerOptions · ProviderOptions

Provider-specific options for the internal structuring agent

Callbacks

onStepFinish · (step: StepResult) => void | Promise<void>

Callback fired after each execution step completes

onFinish · (result: FinishResult) => void | Promise<void>

Callback fired when execution completes

onChunk · (chunk: ChunkType) => void | Promise<void>

Callback fired for each stream chunk (streaming only)

onError · (error: Error) => void | Promise<void>

Callback fired when an error occurs

onAbort · () => void | Promise<void>

Callback fired when execution is aborted

Advanced Options

abortSignal · AbortSignal

Signal to abort the execution

tracingContext · ObservabilityContext

Observability context for tracing

temperature · number

Temperature parameter for controlling randomness

topP · number

Top-p sampling parameter

frequencyPenalty · number

Frequency penalty parameter

presencePenalty · number

Presence penalty parameter

maxCompletionTokens · number

Maximum tokens in the completion

seed · number

Random seed for deterministic generation

AgentGenerateOptions (Legacy)

Legacy options for the generateLegacy() method.

Type Parameters

OUTPUT · ZodSchema | JSONSchema7 · default: "undefined"

Schema type for structured output

EXPERIMENTAL_OUTPUT · ZodSchema | JSONSchema7 · default: "undefined"

Schema type for experimental structured output generation alongside tool calls

Properties

Includes all properties from AgentExecutionOptions plus:

output · OutputType | OUTPUT

Schema for structured output (does not work with tools, use experimental_output instead)

experimental_output · EXPERIMENTAL_OUTPUT

Schema for structured output generation alongside tool calls

AgentStreamOptions (Legacy)

Legacy options for the streamLegacy() method.

Type Parameters

OUTPUT · ZodSchema | JSONSchema7 · default: "undefined"

Schema type for structured output

EXPERIMENTAL_OUTPUT · ZodSchema | JSONSchema7 · default: "undefined"

Schema type for experimental structured output generation alongside tool calls

Properties

Includes all properties from AgentExecutionOptions plus:

output · OutputType | OUTPUT

Schema for structured output

experimental_output · EXPERIMENTAL_OUTPUT

Experimental schema for structured output

temperature · number

Temperature parameter for controlling randomness

NetworkOptions

Options for multi-agent network execution via the network() method.

Properties

maxSteps · number · default: "20"

Maximum number of network iterations

routing · object

Routing configuration for agent selection

Show properties

verboseIntrospection · boolean

Enable verbose introspection logging

completion · CompletionConfig

Completion detection configuration

Show properties

scorers · MastraScorer[] · required

Scorers to evaluate task completion

strategy · 'all' | 'any'

Strategy for combining scorer results

onIterationComplete · (info: { iteration: number; isComplete: boolean }) => void

Callback fired after each network iteration

Example Usage

import { Agent } from '@mastra/core/agent';
import { z } from 'zod';

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5'
});

// Basic generate with options
const response = await agent.generate('Hello', {
  maxSteps: 5,
  temperature: 0.7,
  memory: {
    thread: 'thread-123',
    resource: 'user-456'
  }
});

// Stream with callbacks
const stream = await agent.stream('Write a story', {
  onChunk: (chunk) => {
    if (chunk.type === 'text-delta') {
      process.stdout.write(chunk.textDelta);
    }
  },
  onFinish: (result) => {
    console.log('Finished:', result.text);
  }
});

// Structured output
const userSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email()
});

const result = await agent.generate('Extract user info from: John Doe, 30, [e-mail]', {
  structuredOutput: {
    schema: userSchema
  }
});
console.log(result.object); // { name: 'John Doe', age: 30, email: '[e-mail]' }