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(),
}),
})
スキーマを定義するスキーマを定義するへの直接リンク
Workflow の inputSchema と outputSchema は、Standard JSON Schema をサポートする任意のライブラリで定義できます。Zod、Valibot、ArkType などのライブラリが該当します。
- 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();
src/mastra/workflows/test-workflow.ts
import { createWorkflow, createStep } from "@mastra/core/workflows";
import * as v from "valibot";
import { toStandardJsonSchema } from "@valibot/to-json-schema";
const step1 = createStep({...});
export const testWorkflow = createWorkflow({
id: "test-workflow",
inputSchema: toStandardJsonSchema(v.object({
message: v.string()
})),
outputSchema: toStandardJsonSchema(v.object({
output: v.string()
}))
})
.then(step1)
.commit();
src/mastra/workflows/test-workflow.ts
import { createWorkflow, createStep } from "@mastra/core/workflows";
import { type } from "arktype";
const step1 = createStep({...});
export const testWorkflow = createWorkflow({
id: "test-workflow",
inputSchema: type({
message: "string"
}),
outputSchema: type({
output: "string"
})
})
.then(step1)
.commit();
コンストラクターのパラメーターコンストラクターのパラメーターへの直接リンク
id:
string
Workflow の一意な識別子
inputSchema:
StandardJSONSchemaV1
Workflow の入力構造を定義する Standard JSON Schema
outputSchema:
StandardJSONSchemaV1
Workflow の出力構造を定義する Standard JSON Schema
stateSchema?:
StandardJSONSchemaV1
Workflow state の任意の Standard JSON Schema。Mastra の state system を使用すると自動的に挿入されます。指定しない場合、型は 'any' になります。
requestContextSchema?:
StandardJSONSchemaV1
Request Context の値を検証する Standard JSON Schema。指定すると run.start() の開始時に context が検証され、検証に失敗した場合はエラーがスローされます。
schedule?:
WorkflowScheduleConfig | WorkflowScheduleConfig[]
Workflow の任意の cron スケジュール。単一の設定、または複数の頻度で起動するための設定配列を受け取ります。設定すると、Workflow は evented execution engine に自動的に昇格します。使用方法については、スケジュールされた Workflow のガイドを参照してください。
WorkflowScheduleConfig
id?:
string
スケジュールの安定した識別子。スケジュールの配列を渡す場合は必須です。単一のスケジュールオブジェクトを渡す場合、デフォルトは Workflow ID です。
cron:
string
5、6、または 7 パートの cron 式。Workflow の構築時に検証されます。
timezone?:
string
IANA タイムゾーン（例: "America/New_York"）。デフォルトはホストのローカルタイムゾーンです。起動時刻がサーバーのロケールに左右されないよう、本番環境では明示的に設定してください。
inputData?:
TInput
起動のたびに Workflow の入力として渡されるペイロード。
initialState?:
TState
Run の初期 state。
requestContext?:
Record<string, unknown>
Run に付加される Request Context。
metadata?:
Record<string, unknown>
スケジュール行とともに永続化される任意の metadata。
options?:
WorkflowOptions
Workflow の任意のオプション
WorkflowOptions
tracingPolicy?:
TracingPolicy
Workflow の任意の tracing policy
validateInputs?:
boolean
Workflow の入力を検証するかどうかを指定する任意のフラグ。Workflow またはステップの input／resume data にある zodSchema のデフォルト値も適用します。start／resume 時に input／resume data の検証が失敗すると、Workflow は開始／再開せず、代わりにエラーをスローします。ステップの実行時に入力データの検証が失敗すると、そのステップが失敗し、Workflow も失敗してエラーが返されます。
shouldPersistSnapshot?:
(params: { stepResults: Record<string, StepResult<any, any, any, any>>; workflowStatus: WorkflowRunStatus }) => boolean
Workflow のスナップショットを永続化するかどうかを決定する任意のフラグ
pruneSnapshot?:
(params: { snapshot: WorkflowRunState; workflowStatus: WorkflowRunStatus }) => WorkflowRunState
Workflow のスナップショットを永続化する直前に変換する任意のフック。JSON にシリアライズ可能なデータを返し、Workflow の再開に必要なすべての情報（中断されたステップの suspendPayloads、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 の出力（ステータスが 'success' の場合）
error?:
SerializedError
エラーの詳細（ステータスが 'failed' の場合）
steps:
Record<string, StepResult>
各ステップのステータスと出力を含む個別のステップ結果
tripwire?:
StepTripwireInfo
Tripwire の情報（ステータスが '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 の現在の state オブジェクト
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 の情報（ステータスが '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 の現在の state オブジェクト
初期 state を指定して実行する初期 state を指定して実行するへの直接リンク
Workflow Run を開始するときに initialState を渡すと、Workflow state の開始値を設定できます。
const run = await workflow.createRun()
const result = await run.start({
inputData: { value: 'hello' },
initialState: {
counter: 0,
items: [],
},
})
initialState オブジェクトは、Workflow の stateSchema で定義された構造と一致する必要があります。詳しくは、Workflow stateを参照してください。
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 に tripwire をトリガーする Agent ステップが含まれている場合、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 が意図的に実行を停止したこと（たとえば、コンテンツモデレーションのため）を示します。