Pythonワークフロー チェックポイントを 1.13.0 にアップグレードする

Agent Framework 1.13.0 には、Pythonワークフローの実行に対する軽微な破壊的変更が含まれています。 ほとんどのアプリケーションでは、変更 は必要ありません 。 この変更は、正確なスーパーステップ数または反復数に依存するアプリケーション、収束境界で max_iterations 設定、初期メッセージ ソース ID の検査、チェックポイントの配置と順序付けの前提条件を作成するアプリケーションに影響します。

背景

1.13.0 より前では、チェックポイント処理は、記録された境界から実行を再開するために必要なワークフロー状態をキャプチャするという約束を完全に満たしていませんでした。 開始 Executor はスーパーステップとチェックポイント ループの前に実行されているため、最も古いチェックポイントには、開始 Executor の出力と更新された状態が含まれていましたが、元のワークフロー入力は含まれていません。 同様に、要求イベントへの応答は配信され、チェックポイントに記録されずに処理されました。 その結果、どのチェックポイントも、元の入力から開始用エグゼキューターを再生したり、返された応答から人間が介在する継続を再現したりすることはできませんでした。

動作の変更

バージョン 1.13.0 では、これらのギャップが解消されます。 start executor は最初のスーパーステップで実行されるようになり、エントリチェックポイントはそのスーパーステップの前に初期入力を記録し、応答エントリチェックポイントは配信された応答が処理される前にそれらを記録します。 これらの変更により、チェックポイント化されたワークフローの実行は、human-in-the-loop の継続処理を含め、入力から完全に再現可能になります。

Important

これらの変更は、バージョン 1.13.0 より前に作成されたチェックポイントには影響しません。 既存のチェックポイントは引き続きサポートされ、アップグレード後も復元できます。

アクションが必要になる可能性がある変更

面 1.13.0 より前 1.13.0 以降 ユーザーへの影響
Executor の起動 開始エグゼキューターは、スーパーステップループの前に実行されました。 入力は、最初のスーパーステップで実行される開始 Executor に対してキューに入れられます。 新しい実行ごとに、1 つの追加の superstep_started と superstep_completed イベントが生成されます。
反復回数 イテレーション 1 は、開始 Executor が実行された後の最初のスーパーステップを表しました。 イテレーション 1 では、開始 Executor が実行されます。 後の作業は 1 回の繰り返しでシフトします。 以前に $N$ イテレーションが必要だったワークフローには、$N + 1$ が必要になりました。
入力メッセージのソース 最初のメッセージには、ハードコーディングされたソース ID "Workflow" が含まれていました。 最初のメッセージは、開始 Executor の内部エッジを介して配信され、ソース ID INTERNAL_SOURCE_ID(start_executor.id)。 最初のメッセージ ソース ID を読み取りまたはフィルター処理するコードでは、新しい値を使用する必要があります。

再生可能性の向上

面 1.13.0 より前 1.13.0 以降 改善
初期チェックポイント iteration-0 チェックポイントは、開始 Executor の実行後に作成されました。 Executor の出力メッセージと更新された状態がキャプチャされましたが、元の入力はキャプチャされませんでした。 エントリ チェックポイントは、スーパーステップ 1 の前に作成されます。 開始エグゼキューター用にキュー登録された元の入力データを記録します。 エントリ チェックポイントを復元すると、開始エグゼキューターを含む完全な実行が再実行されます。
応答チェックポイント 最初にチェックポイントに記録されずに、要求イベントへの応答が配信されました。 応答エントリ チェックポイントは、応答が配信された後、およびスーパーステップを使用する前に作成されます。 応答エントリのチェックポイントを復元すると、応答を消費する継続が再生されます。

スーパーステップ イベント処理の更新

新しいワークフロー実行では、開始 Executor がスーパーステップ 1 で実行されるため、スーパーステップ イベントのペアがもう 1 つ生成されるようになりました。

  • superstep_started と iteration == 1
  • superstep_completed と iteration == 1

後続の Executor の作業は、1 つのスーパーステップでシフトします。 正確なイベント数を想定するテスト、テレメトリ、進行状況インジケーター、またはその他のコードを更新するか、特定の Executor を固定イテレーションにマップします。

カウントやイテレーションに依存せずにイベントの種類に応答するコードは、変更する必要はありません。

イテレーションの上限を確認する

max_iterationsの制限に、開始 Executor を実行するスーパーステップが含まれるようになりました。 ワークフローで以前に完全な制限を使用していた場合は、構成された値を 1 ずつ増やします。

from agent_framework import WorkflowBuilder

workflow = WorkflowBuilder(
    start_executor=start_executor,
    max_iterations=previous_max_iterations + 1,
).build()

構成された制限に達する前にワークフローが既に収束している場合、変更は必要ありません。

メッセージ ソースの初期チェックを更新する

開始 Executor が初期メッセージのソース ID を使用する場合は、ハードコーディングされた "Workflow" 値を、開始 Executor の内部エッジのソース ID に置き換えます。

1.13.0 より前:

is_workflow_input = ctx.source_executor_ids != ["Workflow"]

1.13.0 以降:

from agent_framework import INTERNAL_SOURCE_ID

is_workflow_input = ctx.source_executor_ids != [INTERNAL_SOURCE_ID(self.id)]

INTERNAL_SOURCE_ID(executor_id) は現在、 "internal:<executor_id>"を返します。 この文字列を構築する代わりにヘルパーを使用して、コードがフレームワークのソース ID 形式に従います。

チェックポイント処理の更新

初期入力チェックポイント

チェックポイント処理を有効にすると、新たに実行されるたびに、 iteration_count == 0にエントリ チェックポイントが作成されるようになりました。 このチェックポイントには、start executor 宛ての転送中メッセージとして、元の入力が含まれています。 復元すると、開始 Executor が再実行され、完全なワークフロー実行が再現されます。

各スーパーステップが完了すると、フレームワークはチェックポイントを作成し続けます。 $N$ スーパーステップを使用した実行では、$N + 1$ チェックポイント (エントリ チェックポイントの後に、完了したスーパーステップごとに 1 つのチェックポイント) が必要です。

イテレーション 0 チェックポイントに、開始 Executor によって生成された状態が含まれていると想定するコードを確認します。 その状態は、スーパーステップ 1 の後に作成されたチェックポイントに表示されるようになりました。

要求/応答チェックポイント

workflow.run(responses=...)を使用してワークフローを続行すると、応答をキューに入れた後、およびそれらを使用するスーパーステップを実行する前に、フレームワークによって応答エントリ チェックポイントが作成されるようになりました。 このチェックポイントを復元すると、記録された応答が再配信され、ワークフローの残りの部分が再生されます。

応答エントリ チェックポイントには、保留中の要求を含む前のチェックポイントと同じ iteration_count があります。 これは別のチェックポイントであり、その previous_checkpoint_id は保留中の要求チェックポイントを指しています。

Important

iteration_count は、human-in-the-loop のチェックポイントの履歴内で一意であるとは限りません。 previous_checkpoint_id チェーンに従ってチェックポイントの順序を決定します。 最新のチェックポイントが必要な場合は、最大の iteration_countを選択するのではなく、チェックポイント ストレージ API を使用します。

移行チェックリスト

  • 正確なスーパーステップ数またはイテレーション数に依存するアサーションとイベント コンシューマーを更新します。
  • 前の制限に達したワークフローに対してのみ、 max_iterations を 1 ずつ増やします。
  • "Workflow"の初期ソース ID チェックをINTERNAL_SOURCE_ID(start_executor.id)に置き換えます。
  • イテレーション 0 チェックポイントを実行前入力チェックポイントとして扱います。
  • iteration_count が一意であると仮定するのではなく、human-in-the-loop チェックポイントを系統ごとに順序付けしてください。
  • エントリ チェックポイントと応答エントリ チェックポイントを再生すると、予想される出力と副作用が生成されることを確認します。

実装の詳細については、「 ワークフロー チェックポイントの完全な再生を許可する」を参照してください。

  • Last updated on