# SagaFlow: A Persistent AI Agent Workflow Framework Based on Temporal

> SagaFlow is an open-source Python framework that combines the Temporal workflow engine with LLMs like Claude. It addresses the issues of state loss and retry difficulties in multi-agent sessions after crashes, providing persistent execution capabilities for scenarios such as code review, debugging, and research.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-22T22:14:46.000Z
- 最近活动: 2026-04-22T22:18:56.786Z
- 热度: 159.9
- 关键词: Temporal, AI Agent, 工作流, 持久化, Python, Claude, 多Agent, SagaFlow
- 页面链接: https://www.zingnex.cn/en/forum/thread/sagaflow-temporal-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/sagaflow-temporal-ai-agent
- Markdown 来源: floors_fallback

---

## Introduction / Main Post: SagaFlow: A Persistent AI Agent Workflow Framework Based on Temporal

SagaFlow is an open-source Python framework that combines the Temporal workflow engine with LLMs like Claude. It addresses the issues of state loss and retry difficulties in multi-agent sessions after crashes, providing persistent execution capabilities for scenarios such as code review, debugging, and research.

## Introduction: When Agent Sessions Encounter Crashes

With the increasing popularity of multi-agent collaboration systems today, developers often face a tricky problem: when a complex code review or debugging task is running, the terminal crashes unexpectedly, the network is interrupted, or a sub-agent gets stuck in a long silent wait—all intermediate states are lost instantly, the retry mechanism becomes a pile of fragile Markdown text, and there's no way to know the exact state of the ongoing task.

This is exactly the core pain point that SagaFlow aims to solve. As a Python framework built on the Temporal workflow engine, SagaFlow provides **persistent execution capabilities** for AI agents, allowing workflows to span session lifecycles, recover automatically after crashes, and ensure reliable delivery of results.

## Project Background and Design Philosophy

npow, the creator of SagaFlow, observed that modern multi-agent systems (such as code review, debugging, and research assistants) usually adopt a parallel sub-agent architecture, coordinating work through temporary state machines in files or memory. This model has several fatal flaws:

- **State Fragility**: Session crashes lead to fragmented intermediate states
- **Lack of Retry Mechanism**: Recovery after failure relies on manually written retry logic
- **Visibility Blind Spots**: Inability to track which subtasks are still running
- **Reinventing the Wheel**: Each skill needs to implement its own persistence layer

As a mature distributed workflow engine, Temporal has already solved problems like persistent execution, state management, and fault recovery. SagaFlow's design philosophy is straightforward: **Don't reinvent the wheel; instead, combine Temporal's powerful capabilities with the flexibility of LLM agents**.

## Core Architecture Analysis

SagaFlow's architecture can be summarized into four layers:

## 1. Precheck and Initialization Layer

When the user executes the `sagaflow launch` command, the system first performs prechecks:
- Automatically install the SessionStart hook to ensure new sessions can perceive historical tasks
- Check and automatically start the Worker daemon process
- Verify the Temporal service connection status

## 2. Temporal Workflow Layer

Workflow definitions are implemented via Temporal's `@workflow.defn` decorator, with core activities including:
- `write_artifact`: File I/O operations
- `spawn_subagent`: Call LLMs via the Anthropic SDK or `claude -p` subprocess
- `emit_finding`: Write results to the inbox and trigger notifications

Temporal ensures that each activity execution has **exactly-once** semantics. Even if the Worker crashes, it can resume execution from the last completed activity after restarting.

## 3. Four-Layer Result Delivery Mechanism

SagaFlow has designed a redundant result delivery system to ensure users don't miss any important outputs:

1. **Command-Line Wait Mode**: The `--await` flag makes the caller block and wait for results
2. **Inbox File**: `~/.sagaflow/INBOX.md` appends all completion records
3. **Session Hook**: New Claude Code sessions automatically display unread results
4. **Desktop Notifications**: Triggered via `osascript` (macOS) or `notify-send` (Linux)

## 4. Skill Ecosystem

SagaFlow includes 11 out-of-the-box skills covering common development scenarios:

| Skill Name | Function Description |
|------------|----------------------|
| hello-world | Framework smoke test |
| deep-qa | Multi-round document/code QA with parallel critics and synthesis |
| deep-debug | Hypothesis-driven debugging process |
| deep-research | 6-dimensional research (WHO/WHAT/HOW/WHERE/WHEN/WHY) |
| deep-design | Specification drafting → multi-round review → final specification |
| deep-plan | Planner-Architect-Critic consensus loop |
| proposal-reviewer | Claim extraction + 4-dimensional review + fact-checking |
| team | Planning → PRD → parallel execution → verification & fix loop |
| autopilot | Full process: Expansion → planning → execution → QA → verification |
| loop-until-done | Falsifiability review + per-standard verification loop |
| flaky-test-diagnoser | Multi-round runs → hypothesis generation → diagnostic report |

All skills share the same transport layer (Anthropic SDK or subprocess) and result delivery mechanism.