跳至主要內容

toAISdkStream()

將 Mastra 串流（Agent、網路或 Workflow）轉換為 AI SDK 相容的串流。當你需要手動轉換 Mastra 串流，以搭配 AI SDK 的 createUIMessageStream() 與 createUIMessageStreamResponse() 使用時，請使用此函式。

在 Mastra 提供的 chatRoute() 或 workflowRoute() 等路由輔助函式之外建立自訂串流端點時，此函式相當實用。

toAISdkStream() 會保留現有的 AI SDK v5／預設行為。如果你的應用程式使用 AI SDK v6 型別，請在選項物件中傳入 version: 'v6'。

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

當來源 Agent 串流包含最終的結構化輸出物件時，toAISdkStream() 會將其作為自訂 AI SDK UI 資料部分輸出：

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

object 欄位包含完整的結構化輸出值。此欄位會將 Mastra 的最終結構化輸出區塊對應至 AI SDK UI 串流。不會輸出部分結構化輸出區塊。

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

Next.js App Router 範例：

app/api/chat/route.ts
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const myAgent = mastra.getAgent('weatherAgent')
  const stream = await myAgent.stream(messages)

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, { from: 'agent' })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
提示

將 messages 傳遞至 originalMessages（位於 createUIMessageStream() 中），可避免 UI 中出現重複的 assistant 訊息。詳情請參閱疑難排解：重複的 assistant 訊息。

參數
「參數」的直接連結

第一個參數是要轉換的 Mastra 串流，可以是下列任一型別：

  • MastraModelOutput - 來自 agent.stream() 的 Agent 串流
  • MastraAgentNetworkStream - 來自 agent.network() 的網路串流
  • MastraWorkflowStream 或 WorkflowRunOutput - Workflow 串流

第二個參數是選項物件：

version?:

'v5' | 'v6'
= 'v5'
選擇要輸出的 AI SDK 串流契約。省略此參數或傳入 'v5'，即可使用現有的預設行為。當你的應用程式使用 AI SDK v6 回應輔助函式的型別時，請傳入 'v6'。

from:

'agent' | 'network' | 'workflow'
= 'agent'
正在轉換的 Mastra 串流型別。

lastMessageId?:

string
（僅限 Agent）對話中最後一則訊息的 ID。

sendStart?:

boolean
= true
（僅限 Agent）是否在串流中傳送開始事件。

sendFinish?:

boolean
= true
（僅限 Agent）是否在串流中傳送完成事件。

sendReasoning?:

boolean
= false
（僅限 Agent）是否在串流中包含 reasoning-delta 區塊。設為 true，即可串流支援延伸思考之模型的推理內容。

sendSources?:

boolean
= false
（僅限 Agent）是否在輸出中包含來源引用。

includeTextStreamParts?:

boolean
= true
（僅限 Workflow）是否在輸出中包含文字串流部分。

messageMetadata?:

(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined
（僅限 Agent）此函式會接收目前的串流部分，並傳回要附加至開始與完成區塊的中繼資料。

onError?:

(error: unknown) => string
（僅限 Agent）處理串流轉換期間錯誤的函式。此函式會接收錯誤，並應傳回錯誤的字串表示。

範例
「範例」的直接連結

轉換 Workflow 串流
「轉換 Workflow 串流」的直接連結

app/api/workflow/route.ts
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { input } = await req.json()
  const workflow = mastra.getWorkflow('myWorkflow')
  const run = workflow.createRun()
  const stream = await run.stream({ inputData: input })

  const uiMessageStream = createUIMessageStream({
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, { from: 'workflow' })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}

轉換網路串流
「轉換網路串流」的直接連結

app/api/network/route.ts
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const routingAgent = mastra.getAgent('routingAgent')
  const stream = await routingAgent.network(messages)

  const uiMessageStream = createUIMessageStream({
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, { from: 'network' })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}

轉換已啟用推理功能的 Agent 串流
「轉換已啟用推理功能的 Agent 串流」的直接連結

app/api/reasoning/route.ts
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const reasoningAgent = mastra.getAgent('reasoningAgent')
  const stream = await reasoningAgent.stream(messages, {
    providerOptions: {
      openai: { reasoningEffort: 'high' },
    },
  })

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, {
        from: 'agent',
        sendReasoning: true,
      })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}

將 Agent 串流轉換為 AI SDK v6 格式
「將 Agent 串流轉換為 AI SDK v6 格式」的直接連結

app/api/chat-v6/route.ts
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const myAgent = mastra.getAgent('weatherAgent')
  const stream = await myAgent.stream(messages)

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, {
        from: 'agent',
        version: 'v6',
      })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}

使用 messageMetadata
「using-messagemetadata」的直接連結

app/api/chat-with-metadata/route.ts
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const myAgent = mastra.getAgent('weatherAgent')
  const stream = await myAgent.stream(messages)

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, {
        from: 'agent',
        messageMetadata: ({ part }) => ({
          timestamp: Date.now(),
          partType: part.type,
        }),
      })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}

使用者端串流轉換
「使用者端串流轉換」的直接連結

如果你在使用者端使用 Mastra 使用者端 SDK（@mastra/client-js），並想將串流轉換為 AI SDK 格式：

client-stream-to-ai-sdk.ts
import { MastraClient } from '@mastra/client-js'
import { createUIMessageStream } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'
import type { ChunkType, MastraModelOutput } from '@mastra/core/stream'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
})

const agent = client.getAgent('weatherAgent')
const response = await agent.stream('What is the weather in Tokyo?')

// Convert the client SDK stream to a ReadableStream<ChunkType>
const chunkStream = new ReadableStream<ChunkType>({
  async start(controller) {
    await response.processDataStream({
      onChunk: async chunk => {
        controller.enqueue(chunk)
      },
    })
    controller.close()
  },
})

// Transform to AI SDK format
const uiMessageStream = createUIMessageStream({
  execute: async ({ writer }) => {
    for await (const part of toAISdkStream(chunkStream as unknown as MastraModelOutput, {
      from: 'agent',
    })) {
      await writer.write(part)
    }
  },
})

for await (const part of uiMessageStream) {
  console.log(part)
}
On this page