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

# 動態 Workflow

> **Beta:** 此功能目前處於 beta 階段。在 API 穩定之前，可能會在沒有提升主要版本號的情況下作出破壞性變更。

動態 Workflow 是以資料而非程式碼表達的 Workflow 定義。每項定義都是一份 JSON 文件，用於描述 Workflow 的 schema 及步驟圖。Mastra 會驗證定義，將其註冊為可執行的 Workflow，然後持久保存至儲存空間，讓它在程序重新啟動後仍然保留。

由於定義不包含 JavaScript closure，任何能產生 JSON 的工具都可以編寫 Workflow，例如 HTTP client、LLM、視覺化編輯器或你自己的工具。註冊後，動態 Workflow 會透過與程式碼定義 Workflow 相同的執行 API 運行。

## 何時使用動態 Workflow

當使用者、Agent、視覺化編輯器或外部系統需要建立 Workflow，而毋須更改應用程式程式碼或重新部署時，便可使用動態 Workflow。

如果 Workflow 屬於應用程式原始碼的一部分，或需要自訂步驟函式，請繼續使用 [`createWorkflow()`](https://mastra.zisheng.pro/zh-HK/docs/workflows/overview) 定義 Workflow。動態 Workflow 可以調用已在 `Mastra` instance 上註冊的 Agent、Tool 及 Workflow。

## 快速開始

以下範例會註冊一個 Tool，並從動態 Workflow 調用該 Tool，然後執行 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/zh-HK/reference/core/addDynamicWorkflow) 時，系統會先驗證定義，然後才變更儲存空間或即時 Workflow registry。

定義使用 JSON Schema，因為它必須能夠經過 JSON 往返轉換而不受影響。`graph` 描述要調用哪些已註冊的組件，以及資料如何在它們之間流動。所有欄位及圖項目的詳情，請參閱[動態 Workflow 定義參考](https://mastra.zisheng.pro/zh-HK/reference/workflows/dynamic-workflow-definition)。

## 建立及更新定義

定義可以來自任何能產生 JSON 的來源。例如，API route 可以接收由視覺化編輯器建立的定義，並直接註冊：

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

### 先註冊依賴套件

加入動態 Workflow 前，請先在同一個 `Mastra` instance 上註冊所引用的組件。Agent 及巢狀 Workflow 項目使用各自的固有 ID。Tool 項目則使用 `Mastra` `tools` object 中的 key，因此快速開始範例會先以 `create-greeting` 註冊 Tool，然後才透過 `toolId` 引用該 key。

如果某個步驟的輸出與下一步的輸入不相符，請使用 `mapping` 項目。Mapping 項目可以讀取 Workflow 輸入及先前步驟的結果，以及 Workflow state 和 request context。[定義參考](https://mastra.zisheng.pro/zh-HK/reference/workflows/dynamic-workflow-definition)列出了支援的 mapping descriptor。

### 取代 Workflow

加入具有相同 `id` 的新定義，即可取代持久保存的定義及即時註冊內容：

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

新的執行會使用更新後的步驟圖。已開始的執行則會繼續使用原本的步驟圖。

### 一併加入巢狀 Workflow

當根 Workflow 引用尚未註冊的輔助 Workflow 時，可使用 [`addDynamicWorkflows()`](https://mastra.zisheng.pro/zh-HK/reference/core/addDynamicWorkflows) 加入完整集合：

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

Mastra 會將整個套件組合作為一個單位驗證，並根據依賴套件決定註冊次序。如果驗證失敗，所有定義都不會被註冊。

### 透過 HTTP 管理定義

應用程式毋須直接存取 `Mastra` instance，也可管理動態 Workflow。請使用下列其中一種介面：

- [Client SDK workflows API](https://mastra.zisheng.pro/zh-HK/reference/client-js/workflows)：從 JavaScript 或 TypeScript client 調用 `upsertDynamicWorkflow()`。
- [伺服器 routes](https://mastra.zisheng.pro/zh-HK/reference/server/routes)：將定義傳送至 `POST /api/stored/workflows`。

在需要驗證身分的伺服器上，管理動態 Workflow 需要 `stored-workflows:read` 及 `stored-workflows:write` 權限。執行已註冊的 Workflow 則需要 `workflows:execute`。

### 持久保存定義

已儲存的定義使用 `workflowDefinitions` 儲存域。Mastra 啟動時會從儲存空間載入有效定義，並依照依賴套件次序註冊。

如果沒有支援此儲存域的 storage adapter，`addDynamicWorkflow()` 仍會在記憶體中註冊 Workflow，但程序重新啟動後，該定義便會遺失。關於 adapter 支援的詳情，請參閱[儲存空間參考](https://mastra.zisheng.pro/zh-HK/reference/storage/overview)。

## 相關內容

- [動態 Workflow 定義](https://mastra.zisheng.pro/zh-HK/reference/workflows/dynamic-workflow-definition)
- [`Mastra.addDynamicWorkflow()`](https://mastra.zisheng.pro/zh-HK/reference/core/addDynamicWorkflow)
- [`Mastra.addDynamicWorkflows()`](https://mastra.zisheng.pro/zh-HK/reference/core/addDynamicWorkflows)
- [Client SDK workflows API](https://mastra.zisheng.pro/zh-HK/reference/client-js/workflows)
- [伺服器 routes](https://mastra.zisheng.pro/zh-HK/reference/server/routes)