Agent クラス

Agent クラスでは、Voice メソッドの再構成、プロパティアクセスパターンの更新、Streaming API の簡素化が行われました。

変更

getAgents から listAgents へ

mastra.getAgents() メソッドは mastra.listAgents() に改名されました。この変更は、複数の値を取得する getter メソッドに list プレフィックスを使用する API 全体の命名規則に合わせたものです。

移行するには、mastra.getAgents() の呼び出しをすべて mastra.listAgents() に置き換えます。

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

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

npm

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

pnpm

pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .

Yarn

yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .

Bun

bun x @mastra/codemod@latest v1/mastra-plural-apis .

RuntimeContext から RequestContext へ

コードベース全体で、RuntimeContext クラスは RequestContext に改名されました。新しい名前は、このクラスがリクエスト固有のデータであることを明確にし、Web Framework の規則とも一致します。

移行するには、すべての import とパラメーター名を RuntimeContext/runtimeContext から 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

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

プロパティへの直接アクセスから getter メソッドへ

agent.llm、agent.tools、agent.instructions への直接アクセスは非推奨です。この変更により、カプセル化と API 全体の設計の一貫性が向上します。

移行するには、プロパティアクセスを対応する getter メソッドに置き換えます。

- 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

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

Voice メソッドを agent.voice 名前空間へ移動

Voice 関連のメソッドが Agent クラスから agent.voice 名前空間へ移動し、Voice API が 1 か所にまとめられました。

移行するには、Voice メソッドの呼び出しを agent.voice 名前空間を使用するよう更新します。

- 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

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

agent.fetchMemory() から (await agent.getMemory()).recall() へ

fetchMemory() メソッドは、非同期の Memory アクセスを明示する API に置き換えられました。

移行するには、fetchMemory() の呼び出しを新しい 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 メソッド名を get* から list* へ変更

API 全体の一貫性を保つため、Agent の Processor メソッド名が get* から list* パターンに変更されました。この変更は、コレクションを返すメソッドに list* を使用する規則に合わせたものです。

移行するには、Processor のメソッド名を更新します。

- 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

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

Zod v3 と v4 の構造化出力スキーマを引き続きサポート

Mastra v1 は、構造化出力スキーマを受け取る公開 Agent API で Zod v3 と Zod v4 の両方のスキーマを引き続き受け付けます。これには agent.generateLegacy()、agent.streamLegacy() などのメソッドと、関連するオプション型が含まれます。

Agent API にすでに Zod スキーマを渡している場合、Zod のバージョン互換性に関する移行は不要です。既存のスキーマ import を維持してください。

import { z as z3 } from 'zod/v3'
import { z as z4 } from 'zod/v4'

await agent.generateLegacy({
  prompt: 'Summarize this ticket',
  output: z3.object({ summary: z3.string() }),
})

await agent.streamLegacy({
  prompt: 'Extract contact info',
  output: z4.object({ email: z4.string().email() }),
})

アプリケーション全体で 1 つの Zod バージョンに統一する場合にのみ、import を更新してください。

AI SDK バージョン別にデフォルトオプションメソッドを改名

レガシー（AI SDK v4）API と AI SDK v5 以降の API を区別するため、デフォルトオプションのメソッド名が変更されました。メソッド名から、対象の AI SDK バージョンを判別できます。

移行するには、使用する AI SDK のバージョンに応じてメソッド名を更新します。

  // 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 からトップレベルの abortSignal へ

abortSignal オプションが modelSettings から Stream と Generate のオプションのトップレベルへ移動しました。これにより、実行制御がモデル固有の設定から分離されます。

移行するには、abortSignal を modelSettings からトップレベルへ移動します。

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

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

output から structuredOutput.schema へ

非推奨の output オプションと experimental_output オプションが削除されました。この変更により、構造化出力は 1 つの安定した API に統一されます。

移行するには、output または experimental_output を structuredOutput.schema に更新します。

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

Agent の id フィールドが必須に

Agent の作成時に id フィールドが必須になりました。以前は明示的な ID なしでも Agent を作成できましたが、今後はサポートされません。

移行するには、すべての Agent 設定に id フィールドを追加します。

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

id には name と同じ値を使用することも、別の識別子を使用することもできます。ID は mastra.getAgentById() の呼び出しで使用され、Mastra インスタンス内で一意である必要があります。

// 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 のレスポンスで機密データを自動的にマスク

Mastra Server は、Agent の Stream レスポンスから機密情報を自動的にマスクするようになりました。これにより、step-start、step-finish、finish の Stream Chunk から、System Prompt、Tool 定義、API キーが誤って公開されるのを防ぎます。

マスク対象：

• LLM リクエストの Payload（System Prompt、Tool スキーマ）を含む request.body
• Step の結果に含まれる metadata.request
• ネストされた Step データに含まれる output.steps[].request

この動作はデフォルトで有効です。完全なリクエストデータへのアクセスが必要な場合（デバッグや内部サービスなど）は、Server Adapter（@mastra/hono や @mastra/express など）を直接使用するときにマスクを無効にできます。

削除

generateVNext メソッドと streamVNext メソッド

非推奨の generateVNext() メソッドと streamVNext() メソッドが削除されました。以前は AI SDK v5 以降との互換性のために使用されていましたが、現在は標準実装になっています。

移行するには、標準の generate() メソッドと stream() メソッドを使用します。

- 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

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

stream() と generate() の format パラメーター

agent.stream() メソッドと agent.generate() メソッドから format パラメーターが削除されました。AI SDK の Stream 変換は @mastra/ai-sdk パッケージで処理するようになりました。この変更では AI SDK 固有のコードを専用パッケージへ移し、Tree Shaking を改善しています。

移行するには、AI SDK 形式への変換に @mastra/ai-sdk の toAISdkStream() 関数を使用します。

- 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() メソッド

toStep() メソッドが Agent クラスから削除されました。明示的に変換せず、Agent を Workflow の Step に直接追加できるようになりました。

移行するには、Agent を Workflow の Step に直接追加します。Workflow が自動的に変換を処理します。

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

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

Agent の TMetrics ジェネリックパラメーター

TMetrics ジェネリックパラメーターが AgentConfig と Agent コンストラクターから削除されました。Metric/Scorer は Agent の型システムの一部ではなく、Scorer API を使用して設定するようになりました。

移行するには、TMetrics ジェネリックパラメーターを削除し、新しい API で Scorer を設定します。

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

Tripwire のレスポンス形式を変更

Tripwire のレスポンス形式は、個別の tripwire フィールドと tripwireReason フィールドから、関連データをすべて含む単一の tripwire オブジェクトへ変更されました。

移行するには、新しいオブジェクト構造から Tripwire データへアクセスするようコードを更新します。

  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
+ }

Streaming レスポンスの場合：

  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
    }
  }

Step の結果にも Tripwire 情報が含まれるようになりました。

  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 のメッセージ形式

prepareStep Callback は、AI SDK v5 以降の Model Message 形式ではなく、MastraDBMessage 形式でメッセージを受け取るようになりました。この変更により、prepareStep と、Agentic Loop の各 Step で実行される新しい Processor メソッド processInputStep が統一されます。

以前の AI SDK v5 以降の形式が必要な場合は、messageList.get.all.aiV5.model() を使用します。

  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 と resourceId から memory オプションへ

threadId と resourceId オプションが agent.stream() と agent.generate() から削除されました。代わりに、Memory をより簡潔に設定できる memory オプションを使用します。

移行するには、threadId と resourceId を memory オプションへ移動します。

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

新しい Thread の作成時には、memory オプションで Thread のメタデータも渡せます。

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