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

# Agent 類別

Agent 類別已更新，包括重新整理語音方法、更新屬性存取模式，以及簡化串流 API。

## 已變更

### `getAgents` 改為 `listAgents`

`mastra.getAgents()` 方法已重新命名為 `mastra.listAgents()`。這項變更配合整個 API 的命名慣例：傳回多個項目的 getter 方法使用 `list` 前綴。

如要遷移，請將所有 `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`。新名稱清楚表明此類別包含個別請求的資料，亦符合網頁框架的慣例。

如要遷移，請將所有匯入及參數名稱從 `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 .
> ```

### 語音方法移至 `agent.voice` 命名空間

語音相關方法已從 Agent 類別移至 `agent.voice` 命名空間，將語音 API 集中整理。

如要遷移，請更新語音方法呼叫，改用 `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()` 方法已由新的 API 取代，以明確表示 Memory 存取是非同步操作。

如要遷移，請以新 API 取代 `fetchMemory()` 呼叫。

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

### 處理器方法名稱從 `get*` 改為 `list*`

為與整體 API 保持一致，Agent 處理器方法已從 `get*` 模式重新命名為 `list*` 模式。這項變更配合以 `list*` 方法傳回集合的慣例。

如要遷移，請更新處理器方法名稱。

```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 版本相容性進行遷移。保留現有的結構描述匯入即可：

```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() }),
})
```

只有當你想在應用程式中統一使用同一個 Zod 版本時，才需要更新匯入。

### 不同 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` 移至串流及產生選項的頂層。執行控制現在位於模型特定設定之外。

如要遷移，請將 `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` 選項已移除。這項變更將結構化輸出統一為單一穩定 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` 相同，亦可使用不同識別碼。呼叫 `mastra.getAgentById()` 時會使用此 ID，而且在你的 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')
```

### 串流 API 回應現在會隱藏敏感資料

Mastra 伺服器現在會自動隱藏 Agent 串流回應中的敏感資料，避免在 `step-start`、`step-finish` 和 `finish` 串流區塊中意外洩露系統提示、Tool 定義及 API 金鑰。

**會隱藏的內容：**

- 包含 LLM 請求承載資料（系統提示、Tool 結構描述）的 `request.body`
- 步驟結果中的 `metadata.request`
- 巢狀步驟資料中的 `output.steps[].request`

此行為預設啟用。如果你需要存取完整請求資料（例如用於除錯或內部服務），直接使用伺服器配接器（例如 `@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 串流轉換現由 `@mastra/ai-sdk` 套件處理。這項變更將 AI SDK 特定程式碼移至專用套件，改善 tree-shaking。

如要遷移，請使用 `@mastra/ai-sdk` 的 `toAISdkStream()` 函式進行 AI SDK 格式轉換。

```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()` 方法

Agent 類別已移除 `toStep()` 方法。現在可直接將 Agent 加入 Workflow 步驟，無需明確轉換。

如要遷移，請將 Agent 直接加入 Workflow 步驟。Workflow 會自動處理轉換。

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

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

### Agent 的 `TMetrics` 泛型參數

`AgentConfig` 和 `Agent` 建構函式已移除 `TMetrics` 泛型參數。指標／scorer 現在使用 scorer API 設定，不再是 Agent 類型系統的一部分。

如要遷移，請移除 `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
+ }
```

串流回應的遷移方式：

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

步驟結果現在亦包含 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` 回呼現在收到 `MastraDBMessage` 格式的訊息，而非 AI SDK v5+ 模型訊息格式。這項變更令 `prepareStep` 與新的 `processInputStep` 處理器方法統一；後者會在 Agent 循環的每個步驟執行。

如果你需要舊有 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` 選項

`agent.stream()` 和 `agent.generate()` 已移除 `threadId` 及 `resourceId` 選項。請改用 `memory` 選項，讓 Memory 設定 API 更簡潔。

如要遷移，請將 `threadId` 和 `resourceId` 移至 `memory` 選項：

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

建立新對話串時，`memory` 選項亦支援傳入對話串中繼資料：

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