跳至主要內容

動態 Workflow

beta

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

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

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

使用動態 Workflow 的時機
「使用動態 Workflow 的時機」的直接連結

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

當 Workflow 屬於應用程式原始碼的一部分，或需要自訂步驟函式時，請繼續使用 createWorkflow() 定義 Workflow。動態 Workflow 可以叫用已在 Mastra 執行個體上註冊的 Agent、Tool 和 Workflow。

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

以下範例會註冊一個 Tool，並從動態 Workflow 中叫用它，接著執行該 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 登錄檔。

定義使用 JSON Schema，因為它必須能經過 JSON 往返轉換。graph 描述要叫用哪些已註冊的元件，以及資料如何在元件之間流動。請參閱動態 Workflow 定義參考，了解所有欄位與圖項目。

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

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

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 狀態與請求內容。定義參考列出支援的對應描述元。

取代 Workflow
「取代 Workflow」的直接連結

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

await mastra.addDynamicWorkflow(updatedDefinition)

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

一併新增巢狀 Workflow
「一併新增巢狀 Workflow」的直接連結

當根 Workflow 參照尚未註冊的輔助 Workflow 時，請使用 addDynamicWorkflows() 新增完整集合：

await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])

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

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

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

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

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

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

若沒有支援此網域的儲存配接器，addDynamicWorkflow() 仍會在記憶體中註冊 Workflow，但處理程序重新啟動後定義便會遺失。請參閱儲存參考，了解配接器支援情況。

On this page