agently-triggerflow

Agently TriggerFlow

アプリケーションが可視的な多段階実行セマンティクスを所有する場合は、TriggerFlow を使用してください。単一の境界付きリクエスト/実行には ModelRequest/AgentExecution を使用し、1 つの Agent がアプリケーション側で作成したステージトポロジーなしに長いタスクの計画、エビデンス、検証、修復を所有する場合は agent.create_task(...) を使用してください。

必要に応じて読む

• グラフ構築、状態、ライフサイクル、Stage ブリッジ、およびメインリポジトリの例: references/overview.md。
• 一時停止/再開スナップショット、リソース復元、保持、再起動の主張: references/recovery.md。
• オプションのランタイムガイダンスと必須の外部待機の比較: references/runtime-intervention.md。
• 安定したアプリケーションストリームの射影: references/stream-bridge.md。
• DevTools グラフ/観測: references/devtools-graph.md。
• 完全な値/シグナルトポロジーのレビュー: ../agently-design/references/execution-topology-validation.md。
• 直接の Stage スコープ、決済、ブリッジ、チャネル、またはリスナーを使用する場合は agently-stage を使用してください。

トポロジーを最優先

実装の前に、次をマッピングしてください:

• 必須の直列値エッジ;
• 独立した分岐と境界付きの結合;
• リクエスト時の観測境界;
• キャンセルまたは破棄しても安全な暫定作業;
• 副作用の順序、外部容量、待機、修復、および終端状態。

batch(...)、for_each(...)、when(...)、および管理された emit を使用して、 ファンアウトと結合をグラフ可視化してください。繰り返しは明示的なバックエッジで表現してください。ライフサイクル、リトライ、またはリビジョンのループを while True チャンクハンドラー内に隠さないでください。

ModelRequest はディスパッチ時のスナップショットです。instant 出力は UI を更新したり、冪等/キャンセル可能な準備を開始したりできますが、結果として得られる観測を必要とする後続のモデルリクエストは、可視的な結合と検証バリアの後に開始しなければなりません。

グラフの隣接性はアクティベーションを証明するものであり、値の転送を証明するものではありません。監査では、ModelRequest、Action、サブフロー、TaskWorkspace/RecordStore、待機/再開、修復、および終端境界を通じて、正確な値、シグナル、ref、およびコンシューマーを追跡してください。

ライフサイクルと状態

• 呼び出し元が非同期境界を所有する場合は、非同期ハンドラーと実行 API を優先してください。同期プロバイダーファサードは内部で Agently-Stage を使用する場合があります。直接のブリッジに関する質問は agently-stage にルーティングしてください。
• flow.start(...) / flow.async_start(...) は、呼び出し元が実行ハンドルを必要としない、有限で自己完結する実行にのみ使用してください。
• 外部 emit、一時停止/再開、保存/ロード、介入、検査、キャンセル、またはホスト制御のクローズには、flow.create_execution(auto_close=False) を使用してください。
• 位置引数の値で開始し、await execution.async_close() でクローズしてください。クローズは実行管理下の nowait 作業をドレインし、未解決の所有権を報告します。
• 再開後の動作は、ダウンストリームチャンク、明示的な再開イベント、または data.is_resume 分岐に配置してください。一時停止された Python フレームはリカバリー契約ではありません。
• 実行状態は実行ごとのチャンクハンドオフを所有します。非同期チャンクでは、非同期の state、emit、および stream メソッドを await してください。セッターは完全な値を置き換えます。append は意図的なリスト蓄積にのみ使用してください。
• flow_data は実行間で共有されます。保存/ロードはその共有値のコピーをシリアライズして置き換えます。分離、CAS、マージ、または並行性の安全性は提供しません。
• TaskWorkspace はファイルを所有し、RecordStore は永続レコードとリカバリーを所有し、ホストストレージはビジネスの永続化を所有します。実行状態にはコンパクトな ref/ステータスを保持し、完全なボディはコールドに保ってください。

同時実行、待機、ストリーム

• create_execution(concurrency=N) は実行全体のハンドラーディスパッチを制限します。 batch(..., concurrency=N) と for_each(..., concurrency=N) はローカルな ファンアウトを制限します。
• ホストの受付、プロバイダー／モデルのレート制限、ブロッキングワーカープールは、 それぞれ別個の負荷要因であり続けます。
• 追跡されない asyncio.create_task(...) の代わりに emit_nowait(...) / async_emit_nowait(...) を使用してください。実行のクローズで 登録された作業が確定します。
• 必須の外部入力を待つには pause_for(..., resume_to=...) を使用してください。 ランタイム介入は、宣言された境界における任意のコンテキストにのみ使用してください。
• PolicyApproval はフレームワークのポリシーゲートを担います。ExecutionExchange は ホストの UI／Webhook／キューのトランスポートを適合させます。TriggerFlow は 割り込み／再開の台帳を担います。
• モデルパーサーのイベントを安定したアプリケーションイベントに変換してください。 生のパーサーパスをフロントエンドプロトコルとして公開しないでください。また、 暫定項目は最終的に検証された出力と突き合わせて調整してください。

リカバリと動的グラフの境界

保存／ロードは TriggerFlow の進行状況と宣言されたリカバリメタデータを担い、 稼働中のクライアント、コールバック、セマフォ、コルーチンフレーム、シークレット、 外部セッション状態は担いません。稼働中の ExecutionResources は、ホスト／プラグイン リゾルバーを通じて復元し、レディ状態になる前に外部参照、バージョン、リース、 フェンストークンを検証してください。ローカルの RecordStore はローカルでの再起動 のみを証明します。実際の共有プロバイダーと運用上のエビデンスがない限り、 分散リカバリを主張しないでください。

開発者が所有する安定したトポロジーは、トップレベルハンドラーを備えたインポート 可能な TriggerFlow モジュール内で直接定義してください。明示的に送信された、または モデルが生成した DAG データは、低頻度の TaskDAG ケースです。 ../agently/references/task-dag.md をお読みください。検証されていないランタイム プランデータを、その場しのぎの TriggerFlow 定義にコンパイルしないでください。

API の形

from agently import Agently, TriggerFlow

flow = TriggerFlow(name="workflow-name")
factory_flow = Agently.create_trigger_flow("factory-workflow")
execution = flow.create_execution(auto_close=False)

when、emit_nowait、pause_for はフロー／ランタイムのメソッドであり、トップ レベルのインポートではありません。@flow.when(...) をデコレーターとして使用 したり、フロー名を TriggerFlow(...) の最初の位置引数として渡したりしないで ください。

アンチパターン

• 独自のイベントバス、ステートマシン、DAG スケジューラー、またはシャドウ実行 ストア。
• シグナル、ジョイン、実行管理された作業の代わりに、スリープ、ポーリング、 ローカルの完了セット、または追跡されないタスクを使用すること。
• 明示的なランタイムリソースとリゾルバーの代わりに、クロージャーでキャプチャ された稼働中のビジネスリソース。
• flow_data を通常の実行ごとの状態として扱うこと。
• 定義とランタイムメタデータの代わりに、DevTools の図をトポロジーの信頼できる 情報源とすること。