@mastra/core/dist/docs/references/reference-ai-sdk-workflow-route.md

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

# workflowRoute()

Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).

Use [`handleWorkflowStream()`](https://mastra.ai/reference/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.

`workflowRoute()` keeps the existing AI SDK v5/default behavior. If your app is typed against AI SDK v6, pass `version: 'v6'`.

> **Agent streaming in workflows:** When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
>
> See [Workflow Streaming](https://mastra.ai/docs/workflows/overview) for more details.

## Usage example

This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.

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

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

You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.

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

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

## Parameters

**version** (`'v5' | 'v6'`): Selects the AI SDK stream contract to emit. Omit it or pass 'v5' for the existing default behavior. Pass 'v6' when your app is typed against AI SDK v6 response helpers. (Default: `'v5'`)

**path** (`string`): The route path (e.g., /workflow or /workflow/:workflowId). Include :workflowId for dynamic workflow routing. (Default: `'/api/workflows/:workflowId/stream'`)

**workflow** (`string`): Fixed workflow ID when not using dynamic routing. (Default: `undefined`)

**includeTextStreamParts** (`boolean`): Whether to include text stream parts in the output. (Default: `true`)

## Additional configuration

You can use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the workflow route, for example to pass additional configuration to the 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,
          },
        },
      }
    },
  }),
})
```