跳至主要內容

Workflow 類別

Workflow 類別可讓你為包含條件分支與資料驗證的複雜操作序列建立狀態機。

使用範例
「使用範例」的直接連結

src/mastra/workflows/test-workflow.ts
import { createWorkflow } from '@mastra/core/workflows'
import { z } from 'zod'

export const workflow = createWorkflow({
  id: 'test-workflow',
  inputSchema: z.object({
    value: z.string(),
  }),
  outputSchema: z.object({
    value: z.string(),
  }),
})

定義 schema
「定義 schema」的直接連結

你可以使用任何支援 Standard JSON Schema 的程式庫，定義 Workflow 的 inputSchema 與 outputSchema。包括 Zod、Valibot 和 ArkType 等程式庫。

src/mastra/workflows/test-workflow.ts
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";

const step1 = createStep({...});

export const testWorkflow = createWorkflow({
  id: "test-workflow",
  inputSchema: z.object({
    message: z.string()
  }),
  outputSchema: z.object({
    output: z.string()
  })
})
  .then(step1)
  .commit();

建構函式參數
「建構函式參數」的直接連結

id:

string
Workflow 的唯一識別碼

inputSchema:

StandardJSONSchemaV1
定義 Workflow 輸入結構的 Standard JSON Schema

outputSchema:

StandardJSONSchemaV1
定義 Workflow 輸出結構的 Standard JSON Schema

stateSchema?:

StandardJSONSchemaV1
Workflow 狀態的選用 Standard JSON Schema。使用 Mastra 的狀態系統時會自動注入。若未指定，型別為 'any'。

requestContextSchema?:

StandardJSONSchemaV1
用於驗證 request context 值的 Standard JSON Schema。提供此項目時，系統會在 run.start() 開始時驗證 context；驗證失敗會擲回錯誤。

schedule?:

WorkflowScheduleConfig | WorkflowScheduleConfig[]
Workflow 的選用 cron 排程。接受單一設定或設定陣列，以多種頻率觸發。設定此項目會自動將 Workflow 升級為事件式執行引擎。用法請參閱排程 Workflow 指南。
WorkflowScheduleConfig

id?:

string
排程的穩定識別碼。傳入排程陣列時為必填。傳入單一排程物件時，預設為 Workflow ID。

cron:

string
由 5、6 或 7 個部分組成的 cron 運算式。建立 Workflow 時會進行驗證。

timezone?:

string
IANA 時區，例如 "America/New_York"。預設為主機的本地時區。在正式環境中請明確設定，以免觸發時間取決於伺服器 locale。

inputData?:

TInput
每次觸發時，作為 Workflow 輸入傳入的 payload。

initialState?:

TState
Run 的初始狀態。

requestContext?:

Record<string, unknown>
附加至 run 的 request context。

metadata?:

Record<string, unknown>
與排程資料列一併保存的任意中繼資料。

options?:

WorkflowOptions
Workflow 的選用選項
WorkflowOptions

tracingPolicy?:

TracingPolicy
Workflow 的選用 tracing 政策

validateInputs?:

boolean
是否驗證 Workflow 輸入的選用旗標。這也會在 Workflow／步驟的輸入／繼續資料中套用 zodSchema 的預設值。若在 start／resume 時輸入／繼續資料驗證失敗，Workflow 不會啟動／繼續，而會擲回錯誤。若步驟執行時輸入資料驗證失敗，該步驟及 Workflow 都會失敗，並回傳錯誤。

shouldPersistSnapshot?:

(params: { stepResults: Record<string, StepResult<any, any, any, any>>; workflowStatus: WorkflowRunStatus }) => boolean
是否保存 Workflow 快照的選用旗標

pruneSnapshot?:

(params: { snapshot: WorkflowRunState; workflowStatus: WorkflowRunStatus }) => WorkflowRunState
在保存 Workflow 快照前立即轉換快照的選用 hook。必須回傳可序列化為 JSON 的資料，並保留 Workflow 繼續執行所需的一切（已暫停步驟的 suspendPayload、suspendedPaths、executionPath 等）。Agent run 在內部會用它縮減快照；使用者 Workflow 預設會保存完整快照。

onFinish?:

(result: WorkflowFinishCallbackResult) => void | Promise<void>
Workflow 以任何狀態（success、failed、suspended、tripwire）完成時叫用的回呼函式。會收到包含狀態、輸出、錯誤與步驟結果的 Workflow 結果。此回呼函式擲回的錯誤會被攔截並記錄，不會向外傳播。
WorkflowFinishCallbackResult

status:

WorkflowRunStatus
Workflow 狀態：'success'、'failed'、'suspended' 或 'tripwire'

result?:

any
Workflow 輸出（status 為 'success' 時）

error?:

SerializedError
錯誤詳細資料（status 為 'failed' 時）

steps:

Record<string, StepResult>
包含狀態與輸出的個別步驟結果

tripwire?:

StepTripwireInfo
Tripwire 資訊（status 為 'tripwire' 時）

runId:

string
此 Workflow run 的唯一識別碼

workflowId:

string
Workflow 的識別碼

resourceId?:

string
選用資源識別碼（建立 run 時若有提供）

getInitData:

() => any
回傳傳給 Workflow 之初始輸入資料的函式

mastra?:

Mastra
Mastra 執行個體（若 Workflow 已向 Mastra 註冊）

requestContext:

RequestContext
以請求為範圍的 context 資料

logger:

IMastraLogger
Workflow 的 logger 執行個體

state:

Record<string, any>
Workflow 目前的狀態物件

onError?:

(errorInfo: WorkflowErrorCallbackInfo) => void | Promise<void>
只在 Workflow 失敗（failed 或 tripwire 狀態）時叫用的回呼函式。會收到錯誤詳細資料與步驟結果。此回呼函式擲回的錯誤會被攔截並記錄，不會向外傳播。
WorkflowErrorCallbackInfo

status:

'failed' | 'tripwire'
Workflow 狀態（'failed' 或 'tripwire'）

error?:

SerializedError
錯誤詳細資料

steps:

Record<string, StepResult>
包含狀態與輸出的個別步驟結果

tripwire?:

StepTripwireInfo
Tripwire 資訊（status 為 'tripwire' 時）

runId:

string
此 Workflow run 的唯一識別碼

workflowId:

string
Workflow 的識別碼

resourceId?:

string
選用資源識別碼（建立 run 時若有提供）

getInitData:

() => any
回傳傳給 Workflow 之初始輸入資料的函式

mastra?:

Mastra
Mastra 執行個體（若 Workflow 已向 Mastra 註冊）

requestContext:

RequestContext
以請求為範圍的 context 資料

logger:

IMastraLogger
Workflow 的 logger 執行個體

state:

Record<string, any>
Workflow 目前的狀態物件

使用初始狀態執行
「使用初始狀態執行」的直接連結

啟動 Workflow run 時，可以傳入 initialState，設定 Workflow 狀態的起始值：

const run = await workflow.createRun()

const result = await run.start({
  inputData: { value: 'hello' },
  initialState: {
    counter: 0,
    items: [],
  },
})

initialState 物件應符合 Workflow stateSchema 所定義的結構。更多詳細資料請參閱 Workflow 狀態。

Workflow 狀態
「Workflow 狀態」的直接連結

Workflow 的 status 代表目前的執行狀態。可能的值如下：

success:

string
所有步驟都已成功執行完畢，並產生有效的結果輸出

failed:

string
Workflow 執行期間發生錯誤，並可取得錯誤詳細資料

suspended:

string
Workflow 執行已暫停並等待繼續，且包含已暫停步驟的資訊

tripwire:

string
Workflow 已由 processor tripwire 終止。Workflow 中的 Agent 步驟觸發 tripwire（例如內容遭 guardrail 封鎖）時，就會發生此情況。結果中可取得 tripwire 資訊。

處理 tripwire 狀態
「處理 tripwire 狀態」的直接連結

Workflow 包含的 Agent 步驟觸發 tripwire 時，Workflow 會以 status: 'tripwire' 回傳，並包含 tripwire 詳細資料：

const run = await workflow.createRun()
const result = await run.start({ inputData: { message: 'Hello' } })

if (result.status === 'tripwire') {
  console.log('Workflow terminated by tripwire:', result.tripwire?.reason)
  console.log('Processor ID:', result.tripwire?.processorId)
  console.log('Retry requested:', result.tripwire?.retry)
}

這不同於表示非預期錯誤的 status: 'failed'。Tripwire 狀態表示 processor 刻意停止執行（例如為了內容審核）。

On this page