Zing Forum

Reading

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.

TemporalAI Agent工作流持久化PythonClaude多AgentSagaFlow
Published 2026-04-23 06:14Recent activity 2026-04-23 06:18Estimated read 8 min
SagaFlow: A Persistent AI Agent Workflow Framework Based on Temporal
1

Section 01

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.

2

Section 02

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.

3

Section 03

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.

4

Section 04

Core Architecture Analysis

SagaFlow's architecture can be summarized into four layers:

5

Section 05

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
6

Section 06

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.

7

Section 07

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)
8

Section 08

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.