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

# 動態 Workflow

> **Beta:** 此功能目前為 beta 版。在 API 穩定之前，可能會在未提升主要版本號的情況下推出破壞性變更。

動態 Workflow 是以資料而非程式碼表示的 Workflow 定義。定義是一份 JSON 文件，用來描述 Workflow 的 schema 與步驟圖。Mastra 會驗證定義並將其註冊為可執行的 Workflow，接著將它持久保存至儲存空間，使其在處理程序重新啟動後仍然存在。

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

## 使用動態 Workflow 的時機

當使用者、Agent、視覺化編輯器或外部系統需要在不變更應用程式程式碼或重新部署的情況下建立 Workflow 時，請使用動態 Workflow。

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

## 快速開始

以下範例會註冊一個 Tool，並從動態 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/zh-TW/reference/core/addDynamicWorkflow) 時，會先驗證定義，再變更儲存空間或即時 Workflow 登錄檔。

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

## 建立及更新定義

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

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

### 先註冊相依項目

新增動態 Workflow 之前，請先在同一個 `Mastra` 執行個體上註冊被參照的元件。Agent 和巢狀 Workflow 項目使用其固有 ID。Tool 項目使用它在 `Mastra` `tools` 物件中的 key，因此快速開始範例會先以 `create-greeting` 註冊 Tool，再透過 `toolId` 參照該 key。

當某個步驟的輸出與下一個步驟的輸入不相符時，請使用 `mapping` 項目。對應項目可以從 Workflow 輸入與先前步驟結果中讀取資料，也能讀取 Workflow 狀態與請求內容。[定義參考](https://mastra.zisheng.pro/zh-TW/reference/workflows/dynamic-workflow-definition)列出支援的對應描述元。

### 取代 Workflow

新增具有相同 `id` 的新定義，即可取代持久保存的定義與即時註冊項目：

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

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

### 一併新增巢狀 Workflow

當根 Workflow 參照尚未註冊的輔助 Workflow 時，請使用 [`addDynamicWorkflows()`](https://mastra.zisheng.pro/zh-TW/reference/core/addDynamicWorkflows) 新增完整集合：

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

Mastra 會將此組合視為單一單位進行驗證，並根據相依關係決定註冊順序。若驗證失敗，所有定義都不會註冊。

### 透過 HTTP 管理定義

應用程式不需要直接存取 `Mastra` 執行個體也能管理動態 Workflow。請使用以下其中一種介面：

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

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

### 持久保存定義

儲存的定義使用 `workflowDefinitions` 儲存網域。啟動時，Mastra 會從儲存空間載入有效定義，並依相依順序註冊。

若沒有支援此網域的儲存配接器，`addDynamicWorkflow()` 仍會在記憶體中註冊 Workflow，但處理程序重新啟動後定義便會遺失。請參閱[儲存參考](https://mastra.zisheng.pro/zh-TW/reference/storage/overview)，了解配接器支援情況。

## 相關資源

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