> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Agent クラス

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

## 変更

### `getAgents` から `listAgents` へ

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

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> **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` から `RequestContext` へ

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

移行するには、すべての import とパラメーター名を `RuntimeContext`/`runtimeContext` から `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:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/runtime-context .
> ```

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

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

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

```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:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/agent-property-access .
> ```

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

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

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

```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:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/agent-voice .
> ```

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

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

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

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

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

```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:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> 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 を維持してください。

```ts
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 のバージョンに応じてメソッド名を更新します。

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

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

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/agent-abort-signal .
> ```

### `output` から `structuredOutput.schema` へ

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

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

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

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

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

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

```diff
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 インスタンス内で一意である必要があります。

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

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()` メソッドを使用します。

```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:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> 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()` 関数を使用します。

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

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

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

```diff
- 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 を設定します。

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

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

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

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

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

Streaming レスポンスの場合：

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

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

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

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

以前の AI SDK v5 以降の形式が必要な場合は、`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` と `resourceId` から `memory` オプションへ

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

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

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

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

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