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

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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/streaming/workflow-streaming) 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,
          },
        },
      }
    },
  }),
})
```