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

# handleChatStream()

與框架無關的處理器，可用於以 AI SDK 相容格式串流 Agent 聊天。如需在 Hono 或 Mastra 本身的 [apiRoutes](https://mastra.zisheng.pro/zh-HK/docs/server/custom-api-routes) 功能以外處理聊天串流，請直接使用此函數。

`handleChatStream()` 會傳回 `ReadableStream`，你可使用 [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response) 加以包裝。

`handleChatStream()` 會保留現有的 AI SDK v5／預設行為。如果你的應用程式是按 AI SDK v6 定型，請傳入 `version: 'v6'`。

如果你想在 Mastra 伺服器內建立聊天路由，請使用 [`chatRoute()`](https://mastra.zisheng.pro/zh-HK/reference/ai-sdk/chat-route)。

## UI 串流中的結構化輸出

當你將 `structuredOutput` 傳至底層 Agent 執行程序時，最終的結構化輸出物件會在 AI SDK 相容的 UI 串流中作為自訂資料部分輸出：

```json
{
  "type": "data-structured-output",
  "data": {
    "object": {}
  }
}
```

`object` 欄位包含完整的結構化輸出值。Mastra 只會為最終的結構化輸出物件輸出此事件。UI 串流不會公開部分結構化輸出區塊。

可使用 AI SDK UI 的自訂資料處理功能（例如 `onData`）讀取此事件，或從訊息資料部分加以呈現。

## 使用範例

Next.js App Router 範例：

```typescript
import { handleChatStream } from '@mastra/ai-sdk'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/src/mastra'

export async function POST(req: Request) {
  const params = await req.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weatherAgent',
    params,
    messageMetadata: () => ({ createdAt: new Date().toISOString() }),
  })
  return createUIMessageStreamResponse({ stream })
}
```

## 參數

**version** (`'v5' | 'v6'`): 選擇要輸出的 AI SDK 串流規範。如要使用現有的預設行為，請省略此項或傳入 'v5'。如果你的應用程式是按 AI SDK v6 回應輔助函數定型，請傳入 'v6'。 (Default: `'v5'`)

**mastra** (`Mastra`): 包含已註冊 Agent 的 Mastra 執行個體。

**agentId** (`string`): 聊天所使用的 Agent ID。

**agentVersion** (`{ versionId: string } | { status?: 'draft' | 'published' }`): 選擇特定 Agent 版本。傳入 { versionId: '\<id>' } 以指定確切版本，或傳入 { status: 'draft' }／{ status: 'published' } 按狀態解析。必須先設定 Editor。

**params** (`ChatStreamHandlerParams`): 聊天串流的參數，包括訊息及可選的恢復資料。

**params.messages** (`UIMessage[]`): 對話中的訊息陣列。

**params.resumeData** (`Record<string, any>`): 用於恢復已暫停 Agent 執行程序的資料。必須設定 runId。

**params.runId** (`string`): 執行 ID。提供 resumeData 時必須設定。

**params.providerOptions** (`Record<string, Record<string, unknown>>`): 傳至語言模型的 Provider 專用選項（例如 { openai: { reasoningEffort: "high" } }）。此值會與 defaultOptions.providerOptions 合併，而 params 的優先次序較高。

**params.requestContext** (`RequestContext`): 傳至 Agent 執行程序的請求內容。

**defaultOptions** (`AgentExecutionOptions`): 傳至 Agent 執行程序的預設選項。這些選項會與 params 合併，而 params 的優先次序較高。

**sendStart** (`boolean`): 是否在串流中傳送開始事件。 (Default: `true`)

**sendFinish** (`boolean`): 是否在串流中傳送完成事件。 (Default: `true`)

**sendReasoning** (`boolean`): 是否在串流中包括推理步驟。 (Default: `false`)

**sendSources** (`boolean`): 是否在串流中包括來源引文。 (Default: `false`)

**onError** (`(error: unknown) => string`): 串流遇到錯誤時呼叫。請傳回將以錯誤訊息形式傳送至 client 的字串。你可使用此項，在錯誤傳至 client 前移除敏感資料，例如防止內部基礎架構詳情洩漏給終端使用者。

**messageMetadata** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): 此函數接收目前的串流部分，並傳回要附加至開始及完成區塊的元資料。詳情請參閱 AI SDK 訊息元資料文件。