跳至主要內容

handleChatStream()

與框架無關的處理器，可用於以 AI SDK 相容格式串流 Agent 聊天。如需在 Hono 或 Mastra 本身的 apiRoutes 功能以外處理聊天串流，請直接使用此函數。

handleChatStream() 會傳回 ReadableStream，你可使用 createUIMessageStreamResponse() 加以包裝。

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

如果你想在 Mastra 伺服器內建立聊天路由，請使用 chatRoute()。

UI 串流中的結構化輸出
UI 串流中的結構化輸出 的直接連結

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

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

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

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

使用範例
使用範例 的直接連結

Next.js App Router 範例：

app/api/chat/route.ts
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'
= 'v5'
選擇要輸出的 AI SDK 串流規範。如要使用現有的預設行為，請省略此項或傳入 'v5'。如果你的應用程式是按 AI SDK v6 回應輔助函數定型，請傳入 'v6'。

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
= true
是否在串流中傳送開始事件。

sendFinish?:

boolean
= true
是否在串流中傳送完成事件。

sendReasoning?:

boolean
= false
是否在串流中包括推理步驟。

sendSources?:

boolean
= false
是否在串流中包括來源引文。

onError?:

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

messageMetadata?:

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