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

# workflowRoute()

创建使用 AI SDK 格式流式传输 Workflow 执行的路由处理程序。此函数会注册一个 HTTP `POST` endpoint，用于接收输入数据、执行 Workflow，并以 AI SDK 兼容格式将响应流式传回客户端。必须在[自定义 API 路由](https://mastra.zisheng.pro/docs/server/custom-api-routes)中使用它。

如果需要与框架无关的处理程序，请使用 [`handleWorkflowStream()`](https://mastra.zisheng.pro/reference/ai-sdk/handle-workflow-stream)。

`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 流式传输](https://mastra.zisheng.pro/docs/workflows/overview)。

## 使用示例

此示例展示如何在 `/workflow` endpoint 设置 Workflow 路由，并使用 ID 为 `weatherWorkflow` 的 Workflow。

```typescript
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。

```typescript
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'`): 选择要输出的 AI SDK stream 协议。省略此项或传入 'v5' 可使用现有默认行为；当应用使用 AI SDK v6 response helper 的类型时，传入 'v6'。 (Default: `'v5'`)

**path** (`string`): 路由路径（例如 /workflow 或 /workflow/:workflowId）。包含 :workflowId 可启用动态 Workflow 路由。 (Default: `'/api/workflows/:workflowId/stream'`)

**workflow** (`string`): 未使用动态路由时的固定 Workflow ID。 (Default: `undefined`)

**includeTextStreamParts** (`boolean`): 是否在输出中包含文本 stream part。 (Default: `true`)

## 其他配置

可以使用 [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) 自定义发送到 Workflow 路由的请求，例如向 Workflow 传递其他配置：

```typescript
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,
          },
        },
      }
    },
  }),
})
```