Dynamic workflows

beta

在 API 稳定之前，可能会出现无需主版本号升级的破坏性变更。

动态工作流是以数据而非代码表达的工作流定义。定义是一个 JSON 文档，描述工作流的 schema 和步骤图。Mastra 会验证该定义并将其注册为可运行的工作流，然后持久化到存储中，以便在进程重启后仍然存在。

由于定义不包含 JavaScript 闭包，任何能生成 JSON 的东西都可以编写工作流。来源包括 HTTP 客户端或 LLM。可视化编辑器或你自己的工具也可以生成定义。注册后，动态工作流通过与代码定义的工作流相同的执行 API 运行。

何时使用动态工作流

当用户、agent、可视化编辑器或外部系统需要在不更改应用代码或重新部署的情况下创建工作流时，请使用动态工作流。

当工作流属于应用源代码或需要自定义步骤函数时，请继续使用 createWorkflow() 定义工作流。动态工作流可以调用已注册在 Mastra 实例上的 agent、工具和工作流。

快速开始

以下示例注册一个工具，并从动态工作流中调用它，然后运行该工作流。LibSQLStore 将定义持久化到 mastra.db，因此 Mastra 可以在重启后恢复它。

src/dynamic-workflow.ts

import { Mastra } from '@mastra/core/mastra'
import { createTool } from '@mastra/core/tools'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const greetingTool = createTool({
  id: 'create-greeting',
  description: 'Create a greeting for a name',
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async ({ name }) => ({
    message: `Hello, ${name}!`,
  }),
})

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  tools: { 'create-greeting': greetingTool },
})

await mastra.addDynamicWorkflow({
  id: 'greeting-workflow',
  description: 'Create a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
    },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
    },
    required: ['message'],
  },
  graph: [
    {
      type: 'tool',
      id: 'greet',
      toolId: 'create-greeting',
    },
  ],
})

const workflow = mastra.getWorkflow('greeting-workflow')
const run = await workflow.createRun()
const result = await run.start({
  inputData: { name: 'Ada' },
})

if (result.status === 'success') {
  console.log(result.result.message)
}

该工作流会打印 Hello, Ada!。调用 addDynamicWorkflow() 会在更改存储或实时工作流注册表之前验证定义。

定义使用 JSON Schema，因为它必须经受 JSON 往返。graph 描述要调用哪些已注册组件以及数据如何在它们之间流动。完整字段和图条目请参阅动态工作流定义参考。

构建和更新定义

定义可以来自任何生成 JSON 的来源。例如，API 路由可以接受由可视化编辑器创建的定义并直接注册它：

const definition = await request.json()
await mastra.addDynamicWorkflow(definition)

先注册依赖项

在添加动态工作流之前，请在同一 Mastra 实例上注册被引用的组件。Agent 和嵌套工作流条目使用其固有 ID。工具条目使用其在 Mastra tools 对象中的键。快速开始示例在引用该键（toolId）之前，先在 create-greeting 下注册了工具。

当一个步骤的输出与下一步骤的输入不匹配时，使用 mapping 条目。映射条目可以读取工作流输入、先前步骤结果以及工作流状态和请求上下文。定义参考列出了支持的映射描述符。

替换工作流

使用相同的 id 添加新定义，以替换持久化的定义和实时注册：

await mastra.addDynamicWorkflow(updatedDefinition)

新的运行使用更新后的图。已经启动的运行继续使用其原始图。

一起添加嵌套工作流

当根工作流引用尚未注册的辅助工作流时，使用 addDynamicWorkflows() 添加完整集合：

await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])

Mastra 会将整个包作为单元进行验证，并根据依赖关系确定注册顺序。如果验证失败，则不会注册任何定义。

通过 HTTP 管理定义

应用无需直接访问 Mastra 实例即可管理动态工作流。使用以下接口之一：

• Client SDK workflows API：从 JavaScript 或 TypeScript 客户端调用 upsertDynamicWorkflow()。
• 服务端路由：将定义发送到 POST /api/stored/workflows。

在启用身份验证的服务器上，动态工作流管理需要 stored-workflows:read 和 stored-workflows:write 权限。运行已注册的工作流需要 workflows:execute 权限。

持久化定义

存储的定义使用 workflowDefinitions 存储域。启动时，Mastra 从存储加载活动定义并按依赖顺序注册它们。

如果没有支持该域的存储适配器，addDynamicWorkflow() 仍会在内存中注册工作流，但定义会在进程重启后丢失。适配器支持情况请参阅存储参考。

相关内容

• 动态工作流定义
• Mastra.addDynamicWorkflow()
• Mastra.addDynamicWorkflows()
• Client SDK workflows API
• 服务端路由