Run.timeTravel()

.timeTravel() メソッドは、保存されたスナップショットデータまたは指定したカスタムコンテキストを使用し、任意のステップから Workflow を再実行します。失敗した Workflow のデバッグや、異なる入力による個々のステップのテストに使用できます。Workflow 全体を再実行せずにエラーから復旧することもできます。

使用例

const run = await workflow.createRun()

const result = await run.timeTravel({
  step: 'step2',
  inputData: { value: 10 },
})

パラメーター

step:

Step<string, any, TInputSchema, any, any, any, TEngineType> | [...Step<string, any, any, any, any, any, TEngineType>[], Step<string, any, TInputSchema, any, any, any, TEngineType>] | string | string[]

実行を開始する対象のステップ。Step インスタンス、Step の配列（ネストされた Workflow の場合）、ステップ ID の文字列、またはステップ ID の文字列配列を指定できます。ネストされた Workflow のステップには、ドット記法または配列（例: 'nestedWorkflow.step3' または ['nestedWorkflow', 'step3']）を使用します

inputData?:

z.infer<TInputSchema>

対象ステップの入力データ。ステップの入力スキーマに一致する必要があります。指定しない場合は、Workflow のスナップショットにあるデータを使用します

resumeData?:

any

Workflow が以前に中断されていた場合に渡す再開データ

initialState?:

z.infer<TState>

Workflow Run に設定する初期状態。実行前に Workflow レベルの状態を設定するために使用します

context?:

TimeTravelContext<any, any, any, any>

対象ステップより前のステップ結果を含む実行コンテキスト。各キーはステップ ID で、その値は status、payload、output、startedAt、endedAt、suspendPayload、resumePayload を含む StepResult オブジェクトです

nestedStepsContext?:

Record<string, TimeTravelContext<any, any, any, any>>

ネストされた Workflow ステップのコンテキスト。ネストされた Workflow ID をキーとし、それぞれにその Workflow のステップ結果が含まれます

requestContext?:

RequestContext

タイムトラベル実行中に使用する Request Context データ

outputWriter?:

(chunk: TOutput) => Promise<void>

生成された出力チャンクを処理する任意の非同期関数

tracingContext?:

TracingContext

子 span の作成と metadata の追加に使用する Tracing context。Mastra の tracing system を使用すると自動的に挿入されます。

currentSpan?:

Span

子 span の作成と metadata の追加に使用する現在の span。実行中にカスタムの子 span を作成したり、span attribute を更新したりするために使用します。

tracingOptions?:

TracingOptions

Tracing 設定のオプション。

metadata?:

Record<string, any>

ルート trace span に追加する metadata。ユーザー ID、セッション ID、feature flag などのカスタム属性を追加する場合に役立ちます。

requestContextKeys?:

string[]

この trace の metadata として抽出する追加の RequestContext キー。ネストされた値にはドット記法（例: 'user.id'）を使用できます。

traceId?:

string

この実行に使用する trace ID（1〜32 文字の 16 進数）。指定すると、この trace は指定した trace の一部になります。

parentSpanId?:

string

この実行に使用する親 span ID（1〜16 文字の 16 進数）。指定すると、ルート span はこの span の子として作成されます。

tags?:

string[]

この trace に適用する tag。trace の分類とフィルタリングに使用する文字列ラベルです。

outputOptions?:

OutputOptions

出力設定のオプション。

includeState?:

boolean

結果に Workflow Run の状態を含めるかどうか。

includeResumeLabels?:

boolean

結果に resume label を含めるかどうか。

戻り値

result:

Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>

ステップの出力とステータスを含む Workflow の実行結果で解決される Promise

traceId?:

string

Tracing が有効な場合に、この実行に関連付けられる trace ID。ログの関連付けや実行フローのデバッグに使用します。

spanId?:

string

Tracing が有効な場合に、この実行に関連付けられるルート span ID。span 単位の検索と関連付けに使用します。

その他の使用例

カスタムコンテキストを使用したタイムトラベル

const result = await run.timeTravel({
  step: 'step2',
  context: {
    step1: {
      status: 'success',
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
  },
})

ネストされた Workflow のステップへのタイムトラベル

// Using dot notation
const result = await run.timeTravel({
  step: 'nestedWorkflow.step3',
  inputData: { value: 10 },
})

// Using array of step IDs
const result = await run.timeTravel({
  step: ['nestedWorkflow', 'step3'],
  inputData: { value: 10 },
})

初期状態を使用したタイムトラベル

const result = await run.timeTravel({
  step: 'step2',
  inputData: { value: 10 },
  initialState: {
    counter: 5,
    metadata: { source: 'time-travel' },
  },
})

ネストされた Workflow のコンテキストを使用したタイムトラベル

const result = await run.timeTravel({
  step: 'nestedWorkflow.step3',
  context: {
    step1: {
      status: 'success',
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
    nestedWorkflow: {
      status: 'running',
      payload: { step1Result: 2 },
      startedAt: Date.now(),
    },
  },
  nestedStepsContext: {
    nestedWorkflow: {
      step2: {
        status: 'success',
        payload: { step1Result: 2 },
        output: { step2Result: 3 },
        startedAt: Date.now(),
        endedAt: Date.now(),
      },
    },
  },
})

注意事項

• タイムトラベルは永続化された Workflow スナップショットを使用するため、Storage を設定する必要があります
• Workflow を再実行すると、Storage から既存のスナップショットが読み込まれます（利用可能な場合）
• 対象ステップより前のステップ結果は、スナップショットまたは指定したコンテキストから再構築されます
• 指定したステップから、指定または再構築された入力データを使用して実行が開始されます
• Workflow はその時点から完了まで続行されます
• まだ実行されていない Workflow でも、開始するステップのカスタムコンテキストまたは入力データを指定すれば、タイムトラベルを使用できます。

関連項目

• タイムトラベル
• Workflow の概要
• Workflow.createRun()
• スナップショット
• 中断と再開