workflowRoute()

为使用 AI SDK 格式的流式工作流执行创建工作流路由处理程序。此函数注册一个 HTTP POST 端点，该端点接受输入数据、执行工作流，并以 AI SDK 兼容格式将响应流式返回给客户端。你必须在 自定义 API 路由 中使用它。

🌐 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.

如果你需要一个与框架无关的处理器，请使用 handleWorkflowStream()。

🌐 Use handleWorkflowStream() if you need a framework-agnostic handler.

工作流中的代理流

当工作流步骤将代理的流传输给工作流写入器（例如 await response.fullStream.pipeTo(writer)）时，代理的文本块和工具调用会实时转发到 UI 流，即使代理在工作流步骤内运行也是如此。

🌐 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 for more details.

使用示例

🌐 Usage example

此示例演示了如何在 /workflow 端点设置使用 ID 为 weatherWorkflow 的工作流的工作流路线。

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

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 使用动态工作流路由。URL /workflow/weatherWorkflow 将解析到 ID 为 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.

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",
      }),
    ],
  },
});

参数

🌐 Parameters

path?:

string

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

The route path (e.g., `/workflow` or `/workflow/:workflowId`). Include `:workflowId` for dynamic workflow routing.

workflow?:

string

= undefined

Fixed workflow ID when not using dynamic routing.

includeTextStreamParts?:

boolean

= true

Whether to include text stream parts in the output.

附加配置

🌐 Additional configuration

你可以使用 prepareSendMessagesRequest 来自定义发送到工作流路由的请求，例如向工作流传递额外的配置：

🌐 You can use prepareSendMessagesRequest to customize the request sent to the workflow route, for example to pass additional configuration to the 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
          }
        },
      };
    },
  }),
});