Agent Class

The Agent class has been updated with reorganized voice methods, updated property access patterns, and streamlined streaming APIs.

Changed

getAgents to listAgents

The mastra.getAgents() method has been renamed to mastra.listAgents(). This change aligns with the naming convention used across the API where plural getter methods use the list prefix.

To migrate, replace all calls to mastra.getAgents() with mastra.listAgents().

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/mastra-plural-apis .

RuntimeContext to RequestContext

The RuntimeContext class has been renamed to RequestContext throughout the codebase. This change provides clearer naming that better describes its purpose as request-specific data and aligns with web framework conventions.

To migrate, update all imports and parameter names from RuntimeContext/runtimeContext to RequestContext/requestContext.

- import { RuntimeContext } from '@mastra/core/runtime-context';
+ import { RequestContext } from '@mastra/core/request-context';

- const runtimeContext = new RuntimeContext();
- runtimeContext.set('userTier', 'enterprise');
+ const requestContext = new RequestContext();
+ requestContext.set('userTier', 'enterprise');

- await agent.generate(messages, { runtimeContext });
+ await agent.generate(messages, { requestContext });

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/runtime-context .

Direct property access to getter methods

Direct property access to agent.llm, agent.tools, and agent.instructions is deprecated. This change provides better encapsulation and consistency with the broader API design.

To migrate, replace property access with the corresponding getter methods.

- const llm = agent.llm;
- const tools = agent.tools;
- const instructions = agent.instructions;
+ const llm = agent.getLLM();
+ const tools = agent.getTools();
+ const instructions = agent.getInstructions();

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/agent-property-access .

Voice methods moved to agent.voice namespace

Voice-related methods have been moved from the Agent class to the agent.voice namespace. This change provides better organization and clearer separation of concerns.

To migrate, update voice method calls to use the agent.voice namespace.

- await agent.speak('Hello');
- await agent.listen();
- const speakers = agent.getSpeakers();
+ await agent.voice.speak('Hello');
+ await agent.voice.listen();
+ const speakers = agent.voice.getSpeakers();

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/agent-voice .

agent.fetchMemory() to (await agent.getMemory()).recall()

The fetchMemory() method has been replaced with a more explicit API. This change provides better clarity about the asynchronous nature of memory access.

To migrate, replace fetchMemory() calls with the new API.

- const messages = await agent.fetchMemory({ threadId: 'thread-123' });
+ const memory = await agent.getMemory();
+ const result = await memory.recall({ threadId: 'thread-123' });
+ const messages = result.messages;

Processor method names from get* to list*

Agent processor methods have been renamed from get* to list* pattern for consistency with the broader API. This change aligns with the convention that list* methods return collections.

To migrate, update processor method names.

- const inputProcessors = await agent.getInputProcessors(runtimeContext);
- const outputProcessors = await agent.getOutputProcessors(runtimeContext);
+ const inputProcessors = await agent.listInputProcessors(requestContext);
+ const outputProcessors = await agent.listOutputProcessors(requestContext);

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/agent-processor-methods .

Default options method renames for AI SDK versions

Default options methods have been renamed to clarify legacy (AI SDK v4) vs new (AI SDK v5) APIs. This change helps developers understand which AI SDK version they're targeting.

To migrate, update method names based on which AI SDK version you're using.

  // For legacy AI SDK v4
- const options = await agent.getDefaultGenerateOptions();
- const streamOptions = await agent.getDefaultStreamOptions();
+ const options = await agent.getDefaultGenerateOptionsLegacy();
+ const streamOptions = await agent.getDefaultStreamOptionsLegacy();

  // For new AI SDK v5 (default)
  const streamOptions = await agent.getDefaultStreamOptions();

modelSettings.abortSignal to top-level abortSignal

The abortSignal option has been moved from modelSettings to the top level of stream/generate options. This change provides a clearer separation between model-specific settings and execution control.

To migrate, move abortSignal from modelSettings to the top level.

  agent.stream('Hello', {
-   modelSettings: {
-     abortSignal: abortController.signal,
-   },
+   abortSignal: abortController.signal,
  });

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/agent-abort-signal .

output to structuredOutput.schema

The deprecated output and experimental_output options have been removed. This change consolidates on a single, stable API for structured output.

To migrate, update from output or experimental_output to structuredOutput.schema.

  agent.stream('Hello', {
-   output: z.object({ result: z.string() }),
+   structuredOutput: {
+     schema: z.object({ result: z.string() }),
+   },
  });

Agent id field is now required

The id field is now required when creating an Agent. Previously, agents could be created without an explicit ID, but this is no longer supported.

To migrate, add an id field to all Agent configurations.

  const agent = new Agent({
+   id: 'my-agent',
    name: 'My Agent',
    instructions: 'You are a helpful assistant',
    model: openai('gpt-4'),
  });

The id can be the same as the name, or you can use a different identifier. The ID will be used when calling mastra.getAgentById() and must be unique within your Mastra instance.

// Register agent with Mastra
const mastra = new Mastra({
  agents: {
    myAgent: agent, // key can differ from id
  },
});

// Retrieve by ID
const agent = mastra.getAgentById('my-agent');

Stream API responses now redact sensitive data

The Mastra server now automatically redacts sensitive information from agent stream responses. This prevents accidental exposure of system prompts, tool definitions, and API keys in step-start, step-finish, and finish stream chunks.

What's redacted:

• request.body containing LLM request payloads (system prompts, tool schemas)
• metadata.request in step results
• output.steps[].request in nested step data

This behavior is enabled by default. If you need access to the full request data (e.g., for debugging or internal services), you can disable redaction when using server adapters directly (e.g., @mastra/hono or @mastra/express).

Removed

generateVNext and streamVNext methods

The deprecated generateVNext() and streamVNext() methods have been removed. These methods were previously used for AI SDK v5 compatibility but are now the standard implementation.

To migrate, use the standard generate() and stream() methods.

- const result = await agent.generateVNext('Hello');
- const stream = await agent.streamVNext('Hello');
+ const result = await agent.generate('Hello');
+ const stream = await agent.stream('Hello');

Codemod

You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@beta v1/agent-generate-stream-v-next .

format parameter from stream() and generate()

The format parameter has been removed from agent.stream() and agent.generate() methods. AI SDK stream transformations are now handled by the @mastra/ai-sdk package. This change improves tree-shaking by moving AI SDK-specific code to a dedicated package.

To migrate, use the toAISdkStream() function from @mastra/ai-sdk for AI SDK format conversion.

- const stream = await agent.stream(messages, {
-   format: 'aisdk',
- });

+ import { toAISdkStream } from '@mastra/ai-sdk';
+ 
+ const stream = await agent.stream(messages);
+ const aiSdkStream = toAISdkStream(stream, { from: 'agent' });

agent.toStep() method

The toStep() method has been removed from the Agent class. Agents can now be added directly to workflow steps without explicit conversion.

To migrate, add agents directly to workflow steps. Workflows handle the transformation automatically.

- const step = agent.toStep();
- const workflow = new Workflow({
-   steps: [step],
- });

+ const workflow = new Workflow({
+   steps: [agent],
+ });

TMetrics generic parameter from Agent

The TMetrics generic parameter has been removed from AgentConfig and the Agent constructor. Metrics/scorers are now configured using the scorers API instead of being part of the Agent type system.

To migrate, remove the TMetrics generic parameter and configure scorers using the new API.

- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });

Tripwire response format changed

The tripwire response format has changed from separate tripwire and tripwireReason fields to a single tripwire object containing all related data.

To migrate, update your code to access tripwire data from the new object structure.

  const result = await agent.generate('Hello');

- if (result.tripwire) {
-   console.log(result.tripwireReason);
- }
+ if (result.tripwire) {
+   console.log(result.tripwire.reason);
+   // New fields available:
+   // result.tripwire.retry - whether this step should be retried
+   // result.tripwire.metadata - additional metadata from the processor
+   // result.tripwire.processorId - which processor triggered the tripwire
+ }

For streaming responses:

  for await (const chunk of stream.fullStream) {
    if (chunk.type === 'tripwire') {
-     console.log(chunk.payload.tripwireReason);
+     console.log(chunk.payload.reason);
+     // New fields available:
+     // chunk.payload.retry
+     // chunk.payload.metadata
+     // chunk.payload.processorId
    }
  }

The step results now also include tripwire information:

  const result = await agent.generate('Hello');

  for (const step of result.steps) {
-   // No tripwire info on steps
+   if (step.tripwire) {
+     console.log('Step was blocked:', step.tripwire.reason);
+   }
  }

prepareStep messages format

The prepareStep callback now receives messages in MastraDBMessage format instead of AI SDK v5 model message format. This change unifies prepareStep with the new processInputStep processor method, which runs at each step of the agentic loop.

If you need the old AI SDK v5 format, use messageList.get.all.aiV5.model():

  agent.generate({
    prompt: 'Hello',
    prepareStep: async ({ messages, messageList }) => {
-     // messages was AI SDK v5 ModelMessage format
-     console.log(messages[0].content);
+     // messages is now MastraDBMessage format
+     // Use messageList to get AI SDK v5 format if needed:
+     const aiSdkMessages = messageList.get.all.aiV5.model();

      return { toolChoice: 'auto' };
    },
  });