workflowRoute()

创建使用 AI SDK 格式流式传输 Workflow 执行的路由处理程序。此函数会注册一个 HTTP POST endpoint，用于接收输入数据、执行 Workflow，并以 AI SDK 兼容格式将响应流式传回客户端。必须在自定义 API 路由中使用它。

如果需要与框架无关的处理程序，请使用 handleWorkflowStream()。

workflowRoute() 保留现有的 AI SDK v5 默认行为。如果应用使用 AI SDK v6 类型，请传入 version: 'v6'。

Workflow 中的 Agent 流式传输

当 Workflow step 将 Agent stream pipe 到 Workflow writer（例如 await response.fullStream.pipeTo(writer)）时，即使 Agent 在 Workflow step 内运行，其文本 chunk 和 Tool 调用也会实时转发到 UI stream。

详情请参阅 Workflow 流式传输。

使用示例

此示例展示如何在 /workflow endpoint 设置 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 stream 协议。省略此项或传入 'v5' 可使用现有默认行为；当应用使用 AI SDK v6 response helper 的类型时，传入 'v6'。

path?:

string

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

路由路径（例如 /workflow 或 /workflow/:workflowId）。包含 :workflowId 可启用动态 Workflow 路由。

workflow?:

string

= undefined

未使用动态路由时的固定 Workflow ID。

includeTextStreamParts?:

boolean

= true

是否在输出中包含文本 stream part。

其他配置

可以使用 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,
          },
        },
      }
    },
  }),
})