# 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()`.

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

> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
>
> **npm**:
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```
>
> **pnpm**:
>
> ```bash
> pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .
> ```
>
> **Yarn**:
>
> ```bash
> yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .
> ```
>
> **Bun**:
>
> ```bash
> bun x @mastra/codemod@latest 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`.

```diff
- 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:
>
> ```bash
> npx @mastra/codemod@latest 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.

```diff
- 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:
>
> ```bash
> npx @mastra/codemod@latest 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.

```diff
- 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:
>
> ```bash
> npx @mastra/codemod@latest 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.

```diff
- 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.

```diff
- 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:
>
> ```bash
> npx @mastra/codemod@latest 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.

```diff
// 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.

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

> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
>
> ```bash
> npx @mastra/codemod@latest 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`.

```diff
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.

```diff
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.

```typescript
// 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.

```diff
- 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:
>
> ```bash
> npx @mastra/codemod@latest 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.

```diff
- 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.

```diff
- 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.

```diff
- 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.

```diff
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:

```diff
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:

```diff
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()`:

```diff
agent.generate('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' };
    },
  });
```

### `threadId` and `resourceId` to `memory` option

The `threadId` and `resourceId` options have been removed from `agent.stream()` and `agent.generate()`. Use the `memory` option instead, which provides a cleaner API for memory configuration.

To migrate, move `threadId` and `resourceId` into the `memory` option:

```diff
await agent.stream('Hello', {
-   threadId: 'thread-123',
-   resourceId: 'user-456',
+   memory: {
+     thread: 'thread-123',
+     resource: 'user-456',
+   },
  });
```

The `memory` option also supports passing thread metadata when creating new threads:

```typescript
await agent.stream('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
});
```