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

# handleChatStream()

這是與框架無關的處理器，可用於以 AI SDK 相容格式串流 Agent 聊天。當你需要在 Hono 或 Mastra 本身的 [apiRoutes](https://mastra.zisheng.pro/zh-TW/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-TW/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`): 串流發生錯誤時呼叫。請傳回要作為錯誤訊息傳送至使用者端的字串。你可以用此函式清理錯誤，再將其傳給終端使用者，例如避免內部基礎設施的詳細資訊外洩。

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