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

# workflowRoute()

建立 Workflow 路由處理程式，使用 AI SDK 格式串流執行 Workflow。此函數會註冊一個 HTTP `POST` 端點，用於接收輸入資料、執行 Workflow，並以 AI SDK 相容格式將回應串流傳回用戶端。你必須在[自訂 API 路由](https://mastra.zisheng.pro/zh-HK/docs/server/custom-api-routes)中使用此函數。

如需與框架無關的處理程式，請使用 [`handleWorkflowStream()`](https://mastra.zisheng.pro/zh-HK/reference/ai-sdk/handle-workflow-stream)。

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

> **Workflow 中的 Agent 串流:** 當 Workflow 步驟將 Agent 的串流傳送至 Workflow writer（例如 `await response.fullStream.pipeTo(writer)`）時，即使 Agent 在 Workflow 步驟內執行，其文字區塊和 Tool 呼叫亦會即時轉送至 UI 串流。
>
> 詳情請參閱 [Workflow 串流](https://mastra.zisheng.pro/zh-HK/docs/workflows/overview)。

## 使用範例

以下範例說明如何在 `/workflow` 端點設定 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 串流合約。如要使用現有預設行為，請省略此項或傳入 'v5'。如果你的應用程式以 AI SDK v6 回應輔助函數的型別定義，請傳入 'v6'。 (Default: `'v5'`)

**path** (`string`): 路由路徑（例如 /workflow 或 /workflow/:workflowId）。如要使用動態 Workflow 路由，請加入 :workflowId。 (Default: `'/api/workflows/:workflowId/stream'`)

**workflow** (`string`): 不使用動態路由時的固定 Workflow ID。 (Default: `undefined`)

**includeTextStreamParts** (`boolean`): 是否在輸出中包含文字串流部分。 (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,
          },
        },
      }
    },
  }),
})
```