workflowRoute()

建立 Workflow 路由處理器，使用 AI SDK 格式串流 Workflow 執行作業。此函式會註冊一個 HTTP POST 端點，用來接收輸入資料、執行 Workflow，並以 AI SDK 相容格式將回應串流傳回使用者端。你必須在自訂 API 路由中使用此函式。

如果需要與框架無關的處理器，請使用 handleWorkflowStream()。

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

Workflow 中的 Agent 串流

當 Workflow 步驟將 Agent 的串流管線傳送至 Workflow 寫入器（例如 await response.fullStream.pipeTo(writer)）時，即使 Agent 在 Workflow 步驟內執行，其文字區塊與 Tool 呼叫也會即時轉送至 UI 串流。

詳情請參閱 Workflow 串流。

使用範例

以下範例說明如何在 /workflow 端點設定 Workflow 路由，並使用 ID 為 weatherWorkflow 的 Workflow。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { workflowRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      workflowRoute({
        path: '/workflow',
        workflow: 'weatherWorkflow',
      }),
    ],
  },
})

你也可以根據 workflowId 使用執行階段定義的 Workflow 路由。URL /workflow/weatherWorkflow 會解析為 ID 是 weatherWorkflow 的 Workflow。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { workflowRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      workflowRoute({
        path: '/workflow/:workflowId',
      }),
    ],
  },
})

參數

version?:

'v5' | 'v6'

= 'v5'

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

path?:

string

= '/api/workflows/:workflowId/stream'

路由路徑（例如 /workflow 或 /workflow/:workflowId）。若要使用動態 Workflow 路由，請加入 :workflowId。

workflow?:

string

= undefined

未使用動態路由時的固定 Workflow ID。

includeTextStreamParts?:

boolean

= true

是否在輸出中包含文字串流部分。

其他設定

你可以使用 prepareSendMessagesRequest 自訂傳送至 Workflow 路由的請求，例如將其他設定傳遞給 Workflow：

const { error, status, sendMessage, messages, regenerate, stop } = useChat({
  transport: new DefaultChatTransport({
    api: 'http://localhost:4111/workflow',
    prepareSendMessagesRequest({ messages }) {
      return {
        body: {
          inputData: {
            city: messages[messages.length - 1].parts[0].text,
          },
          // Or resumeData for resuming a suspended workflow
          resumeData: {
            confirmation: messages[messages.length - 1].parts[0].text,
          },
        },
      }
    },
  }),
})