ステップの再試行

Mastraはワークフローステップの一時的な障害に対処するための組み込みの再試行メカニズムを提供しています。これにより、ワークフローは手動での介入を必要とせずに、一時的な問題から優雅に回復することができます。

概要

ワークフロー内のステップが失敗（例外をスロー）した場合、Mastraは設定可能な再試行ポリシーに基づいて、ステップの実行を自動的に再試行できます。これは以下のような問題に対処するのに役立ちます：

ネットワーク接続の問題
サービスの利用不可
レート制限
一時的なリソース制約
その他の一過性の障害

デフォルトの動作

デフォルトでは、ステップが失敗しても再試行されません。これは以下を意味します：

ステップは一度だけ実行されます
失敗した場合、ステップはすぐに失敗としてマークされます
ワークフローは、失敗したステップに依存しない後続のステップの実行を継続します

設定オプション

リトライは2つのレベルで設定できます：

1. ワークフローレベルの設定

ワークフロー内のすべてのステップに対するデフォルトのリトライ設定を設定できます：


const workflow = new Workflow({
  name: "my-workflow",
  retryConfig: {
    attempts: 3, // リトライ回数（最初の試行に加えて）
    delay: 1000, // リトライ間の遅延（ミリ秒）
  },
});

2. ステップレベルの設定

個々のステップにリトライを設定することもできます。これにより、そのステップに対するワークフローレベルの設定が上書きされます：


const fetchDataStep = new Step({
  id: "fetchData",
  execute: async () => {
    // 外部APIからデータを取得
  },
  retryConfig: {
    attempts: 5, // このステップは最大5回リトライします
    delay: 2000, // リトライ間に2秒の遅延を設定
  },
});

リトライパラメータ

retryConfig オブジェクトは以下のパラメータをサポートしています：

パラメータ	型	デフォルト	説明
`attempts`	number	0	リトライ試行回数（初回の試行に加えて）
`delay`	number	1000	リトライ間の待機時間（ミリ秒）

リトライの仕組み

ステップが失敗した場合、Mastraのリトライメカニズムは以下のように動作します：

ステップに残りのリトライ試行回数があるかを確認します
試行回数が残っている場合：
- 試行カウンターを減らします
- ステップを「待機中」状態に移行します
- 設定された遅延時間を待ちます
- ステップの実行を再試行します
試行回数が残っていない、またはすべての試行が使い果たされた場合：
- ステップを「失敗」としてマークします
- ワークフローの実行を継続します（失敗したステップに依存しないステップについて）

リトライ試行中、ワークフロー実行はアクティブなままですが、再試行されている特定のステップについては一時停止されます。

例

基本的なリトライの例


import { Workflow, Step } from "@mastra/core/workflows";
 
// Define a step that might fail
const unreliableApiStep = new Step({
  id: "callUnreliableApi",
  execute: async () => {
    // Simulate an API call that might fail
    const random = Math.random();
    if (random < 0.7) {
      throw new Error("API call failed");
    }
    return { data: "API response data" };
  },
  retryConfig: {
    attempts: 3, // Retry up to 3 times
    delay: 2000, // Wait 2 seconds between attempts
  },
});
 
// Create a workflow with the unreliable step
const workflow = new Workflow({
  name: "retry-demo-workflow",
});
 
workflow.step(unreliableApiStep).then(processResultStep).commit();

ワークフローレベルのリトライとステップでの上書き


import { Workflow, Step } from "@mastra/core/workflows";
 
// Create a workflow with default retry configuration
const workflow = new Workflow({
  name: "multi-retry-workflow",
  retryConfig: {
    attempts: 2, // All steps will retry twice by default
    delay: 1000, // With a 1-second delay
  },
});
 
// This step uses the workflow's default retry configuration
const standardStep = new Step({
  id: "standardStep",
  execute: async () => {
    // Some operation that might fail
  },
});
 
// This step overrides the workflow's retry configuration
const criticalStep = new Step({
  id: "criticalStep",
  execute: async () => {
    // Critical operation that needs more retry attempts
  },
  retryConfig: {
    attempts: 5, // Override with 5 retry attempts
    delay: 5000, // And a longer 5-second delay
  },
});
 
// This step disables retries
const noRetryStep = new Step({
  id: "noRetryStep",
  execute: async () => {
    // Operation that should not retry
  },
  retryConfig: {
    attempts: 0, // Explicitly disable retries
  },
});
 
workflow.step(standardStep).then(criticalStep).then(noRetryStep).commit();

リトライの監視

ログでリトライの試行を監視することができます。Mastraはdebugレベルでリトライ関連のイベントを記録します：


[DEBUG] Step fetchData failed (runId: abc-123)
[DEBUG] Attempt count for step fetchData: 2 remaining attempts (runId: abc-123)
[DEBUG] Step fetchData waiting (runId: abc-123)
[DEBUG] Step fetchData finished waiting (runId: abc-123)
[DEBUG] Step fetchData pending (runId: abc-123)

ベストプラクティス

一時的な障害に対してリトライを使用する: 一時的な障害が発生する可能性のある操作に対してのみリトライを設定してください。確定的なエラー（バリデーションエラーなど）に対しては、リトライは役立ちません。
適切な遅延を設定する: 外部APIコールには、サービスが回復する時間を確保するために、より長い遅延を検討してください。
リトライ回数を制限する: 障害発生時にワークフローが過度に長時間実行されることを防ぐため、極端に高いリトライ回数は設定しないでください。
べき等操作を実装する: リトライされる可能性があるため、ステップのexecute関数がべき等（副作用なく複数回呼び出せる）であることを確認してください。
バックオフ戦略を検討する: より高度なシナリオでは、レート制限がかかる可能性のある操作に対して、ステップのロジックに指数関数的バックオフを実装することを検討してください。