跳至主要內容

動態 Workflow

beta

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

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

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

何時使用動態 Workflow
何時使用動態 Workflow 的直接連結

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

如果 Workflow 屬於應用程式原始碼的一部分，或需要自訂步驟函式，請繼續使用 createWorkflow() 定義 Workflow。動態 Workflow 可以調用已在 Mastra instance 上註冊的 Agent、Tool 及 Workflow。

快速開始
快速開始 的直接連結

以下範例會註冊一個 Tool，並從動態 Workflow 調用該 Tool，然後執行 Workflow。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)
}

Workflow 會輸出 Hello, Ada!。調用 addDynamicWorkflow() 時，系統會先驗證定義，然後才變更儲存空間或即時 Workflow registry。

定義使用 JSON Schema，因為它必須能夠經過 JSON 往返轉換而不受影響。graph 描述要調用哪些已註冊的組件，以及資料如何在它們之間流動。所有欄位及圖項目的詳情，請參閱動態 Workflow 定義參考。

建立及更新定義
建立及更新定義 的直接連結

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

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。定義參考列出了支援的 mapping descriptor。

取代 Workflow
取代 Workflow 的直接連結

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

await mastra.addDynamicWorkflow(updatedDefinition)

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

一併加入巢狀 Workflow
一併加入巢狀 Workflow 的直接連結

當根 Workflow 引用尚未註冊的輔助 Workflow 時，可使用 addDynamicWorkflows() 加入完整集合：

await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])

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

透過 HTTP 管理定義
透過 HTTP 管理定義 的直接連結

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

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

持久保存定義
持久保存定義 的直接連結

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

如果沒有支援此儲存域的 storage adapter，addDynamicWorkflow() 仍會在記憶體中註冊 Workflow，但程序重新啟動後，該定義便會遺失。關於 adapter 支援的詳情，請參閱儲存空間參考。

On this page