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

# Dynamic Workflow

> **Beta:** 此功能处于 Beta 阶段。在 API 稳定之前，即使主版本号不变，也可能发生破坏性变更。

Dynamic Workflow 是以数据而非代码表示的 Workflow 定义。定义是一份描述 Workflow Schema 和步骤图的 JSON 文档。Mastra 会验证该定义、将其注册为可运行的 Workflow，并持久化到 Storage，使其在进程重启后仍然存在。

由于定义不包含 JavaScript 闭包，任何能够生成 JSON 的主体都可以编写 Workflow，例如 HTTP 客户端、LLM、可视化编辑器或你自己的工具。注册后，Dynamic Workflow 会通过与代码定义 Workflow 相同的执行 API 运行。

## 何时使用 Dynamic Workflow

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

如果 Workflow 属于应用源代码或需要自定义步骤函数，请继续使用 [`createWorkflow()`](https://mastra.zisheng.pro/docs/workflows/overview) 定义。Dynamic Workflow 可以调用已经在 `Mastra` 实例上注册的 Agent、Tool 和 Workflow。

## 快速开始

以下示例注册一个 Tool，并从 Dynamic Workflow 调用它，然后运行该 Workflow。`LibSQLStore` 会将定义持久化到 `mastra.db`，因此 Mastra 可以在重启后恢复它。

```typescript
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)
}
```

该 Workflow 会输出 `Hello, Ada!`。调用 [`addDynamicWorkflow()`](https://mastra.zisheng.pro/reference/core/addDynamicWorkflow) 时，会先验证定义，然后才更改 Storage 或实时 Workflow 注册表。

该定义使用 JSON Schema，因为它必须能够完成 JSON 往返转换。`graph` 描述要调用哪些已注册组件，以及数据如何在它们之间流动。所有字段和图条目请参阅 [Dynamic Workflow 定义参考](https://mastra.zisheng.pro/reference/workflows/dynamic-workflow-definition)。

## 构建和更新定义

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

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

### 先注册依赖项

添加 Dynamic Workflow 之前，请在同一个 `Mastra` 实例上注册被引用的组件。Agent 和嵌套 Workflow 条目使用其固有 ID。Tool 条目使用 `Mastra` `tools` 对象中的键，因此快速入门先以 `create-greeting` 注册 Tool，再通过 `toolId` 引用该键。

如果一个步骤的输出与下一步骤的输入不匹配，请使用 `mapping` 条目。Mapping 条目可以从 Workflow 输入、先前步骤结果、Workflow 状态和 Request Context 中读取数据。支持的 Mapping 描述符请参阅[定义参考](https://mastra.zisheng.pro/reference/workflows/dynamic-workflow-definition)。

### 替换 Workflow

添加具有相同 `id` 的新定义，即可替换已持久化定义和实时注册：

```typescript
await mastra.addDynamicWorkflow(updatedDefinition)
```

新 Run 使用更新后的图。已经开始的 Run 会继续使用原图。

### 一起添加嵌套 Workflow

当根 Workflow 引用了尚未注册的辅助 Workflow 时，请使用 [`addDynamicWorkflows()`](https://mastra.zisheng.pro/reference/core/addDynamicWorkflows) 添加完整集合：

```typescript
await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])
```

Mastra 会将该集合视为一个整体进行验证，并根据依赖项确定注册顺序。如果验证失败，则不会注册任何定义。

### 通过 HTTP 管理定义

应用无需直接访问 `Mastra` 实例也能管理 Dynamic Workflow。可使用以下任一接口：

- [Client SDK Workflows API](https://mastra.zisheng.pro/reference/client-js/workflows)：从 JavaScript 或 TypeScript 客户端调用 `upsertDynamicWorkflow()`。
- [Server 路由](https://mastra.zisheng.pro/reference/server/routes)：将定义发送到 `POST /api/stored/workflows`。

在经过身份验证的 Server 上，管理 Dynamic Workflow 需要 `stored-workflows:read` 和 `stored-workflows:write` 权限。运行已注册 Workflow 需要 `workflows:execute`。

### 持久化定义

已存储定义使用 `workflowDefinitions` Storage 域。启动时，Mastra 会从 Storage 加载活动定义，并按依赖顺序注册。

如果没有支持该域的 Storage Adapter，`addDynamicWorkflow()` 仍会在内存中注册 Workflow，但进程重启后定义会丢失。Adapter 支持情况请参阅 [Storage 参考](https://mastra.zisheng.pro/reference/storage/overview)。

## 相关内容

- [Dynamic Workflow 定义](https://mastra.zisheng.pro/reference/workflows/dynamic-workflow-definition)
- [`Mastra.addDynamicWorkflow()`](https://mastra.zisheng.pro/reference/core/addDynamicWorkflow)
- [`Mastra.addDynamicWorkflows()`](https://mastra.zisheng.pro/reference/core/addDynamicWorkflows)
- [Client SDK Workflows API](https://mastra.zisheng.pro/reference/client-js/workflows)
- [Server 路由](https://mastra.zisheng.pro/reference/server/routes)