DeterminFlow
A production-oriented AI workflow runtime that runs uncertain LLMs inside versioned, validated, recoverable deterministic workflows.
- Source repo
- alikon-art/DeterminFlow
- Stars
- ★ 927
- Last updated
- 1mo ago
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Teams with well-defined AI pipelines (e.g., multi-writer + validation + persistence) that want to migrate from a single long-context agent to a node-based, resumable runtime
- Not a fit if
- Teams needing closed-source commercial or network-service use (AGPL-3.0 copyleft)
- Users wanting to migrate existing prompt/skill pipelines with zero rework
- Users unwilling to supply their own model API keys or use the public-benefit model
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
DeterminFlow is a production-oriented AI workflow runtime that organizes LLM calls, scripts, APIs, database operations, and human approvals into versioned, validatable, retryable, recoverable, and auditable workflows. Its core components include four Core Node types (Agent, Script, Approval, Subprocess), a visual Workflow Editor, a FastAPI service, a React console, Cron Automation, WebSocket events, and a Plugin mechanism for packaging complete business capabilities. Each Agent node runs in an isolated session that reads only its local context and uses only whitelisted tools; outputs pass through JSON detection, parsing, repair, and targeted retries. Workflow definitions and inputs are frozen at Task start, and every attempt, token spend, artifact, and checkpoint is persisted so execution can resume from the failed node even after a process restart. The runtime is production-proven in the real AI novel pipeline of Bishu Writing; the open-source bishu-novel plugin contains 7 production workflows, 84 orchestration nodes, 33 Agent/Prompt combinations, and 15 reusable script modules, with node-level context isolation measured to save roughly 70%–89% of tokens. The project is licensed under AGPL-3.0 and maintained by alikon-art.
The execution flow: users define versioned workflows (with variables, conditions, parallelism, loops, human approvals, and subprocesses) via the visual Workflow Editor or API; Task start freezes the workflow definition and inputs; each Agent Node runs in its own session with per-node tool whitelist/blacklist, Workspace, and max-turn settings, producing structured JSON; invalid outputs trigger repair, retry, skip, or human escalation, and downstream nodes can reject results to force targeted upstream rework; Script Nodes handle deterministic work like file conversion, API calls, and database writes; every attempt, error, token count, artifact, and checkpoint is saved, so execution continues past process restarts. Delivery surfaces include FastAPI (http://localhost:8020, docs at /docs), the GET /api/plugins endpoint, a React console, Cron Automation, WebSocket events, and health checks; MCP, Agent/Prompt templates, Skills, and Rules serve as reusable assets, and the Core runs independently of any business Plugin.
- Teams with well-defined AI pipelines (e.g., multi-writer + validation + persistence) that want to migrate from a single long-context agent to a node-based, resumable runtime
- Cost-sensitive product teams that want each model to read only its local context, saving 70%–89% of tokens on real production tasks
- Compliance or cost-control scenarios needing per-node tool permissions and per-model-call token accounting and auditing
- Teams packaging mature AI workflows as Workflow + Agent + Prompt + Skill + Rule bundles for installation by other teams or the community (Plugin mechanism)
- Situations requiring workflows exposed as APIs, managed background processes, Cron Automation, or WebSocket event services
How do you install or deploy this agent?
Option 1 — Desktop installers: download from GitHub Releases (https://github.com/alikon-art/DeterminFlow/releases/latest) or https://determinflow.com/download; Core builds are DeterminFlow_1.1.0_x64-setup.exe (Windows) and DeterminFlow_1.1.0_aarch64.dmg (macOS Apple Silicon); Full builds pre-install bishu-novel 0.2.2 and public-api 0.1.37; the desktop bundles include the runtime, so no Python, Node.js, or Git is needed. Option 2 — From source (macOS/Linux):
git clone https://github.com/alikon-art/DeterminFlow.git
cd DeterminFlow
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.lock
cp .env.example .env
cp config/models_config.example.json config/models_config.json
python run.pyOn Windows PowerShell, use .\.venv\Scripts\python.exe -m pip install -r requirements.lock and copy .env and models_config.json before running run.py. Alternatively, run docker compose up --build. Prerequisites: Python 3.11+, Node.js 22.12+, npm.
How do you use this agent?
After startup, the Web UI is at http://localhost:8020, API docs at http://localhost:8020/docs, and plugin status at GET /api/plugins. On first launch, configure your model API key in the settings page or set DEEPSEEK_API_KEY in .env (model config reads it via ${DEEPSEEK_API_KEY}); you may also opt into the community-provided free models. In the console, use the Workflow Editor to define nodes, variables, and branches and publish a versioned workflow, then trigger Tasks manually, via API/event, or via Cron Automation. During execution you can inspect status and usage at Workflow, Task, Node, attempt, and model-call granularity, and retry, skip, or resume from the failed node on errors. New configuration uses the DETERMINFLOW_* prefix; the community edition runs tasks with 4 local Workflow Executor processes by default—set DETERMINFLOW_WORKFLOW_EXECUTOR_MODE=inline and DETERMINFLOW_WORKFLOW_EXECUTOR_COUNT=1 to fall back to a single process. For Docker, use docker compose up --build. Verification: python -m pytest -q, plus npm run lint, npm run test:extensions, and npm run build in the web directory.
What are this agent's strengths and limitations?
- Node-level context isolation with independent sessions delivers roughly 70%–89% token savings versus long-chain single agents, based on a real production token ledger
- Workflow definitions and inputs are frozen at Task start; checkpoints persist across restarts and execution resumes from the failed node without rerunning completed work
- Per-node tool whitelists/blacklists, max-turn settings, and failure policies, plus structured output with JSON validation, repair, and targeted rework
- Production-proven: the Bishu Writing novel pipeline and the open-source bishu-novel plugin (7 workflows, 84 orchestration nodes, 33 Agent/Prompt combos, 15 script modules)
- Unified console for chat, Workflows, Cron, Skills, Rules, and Plugins, with FastAPI/React/Cron/WebSocket delivery surfaces
- AGPL-3.0 licensing carries copyleft obligations for closed-source commercial integration or network service use—assess before adopting
- Core value depends on versioned nodes and structured definitions, so migrating existing prompt/skill pipelines to node-based workflows requires real effort
- Requires self-provided model API keys (example: DeepSeek) plus Python 3.11+ / Node.js 22.12+ / npm; macOS desktop builds are ad-hoc signed, not notarized, need manual approval to open, and currently update only via manual downloads
- The resource marketplace initially distributes only Skills, the stronger LLM workspace sandbox is still on the Roadmap, and the single-agent comparison token figures are estimates
How does this agent compare with similar options?
The README contrasts DeterminFlow with single-agent frameworks like Codex and Claude: those are well suited to exploring unknown problems, but once a process is defined, DeterminFlow's versioned nodes, local context, structured-output validation, failure-node recovery, per-node tool permissions, and node-level token accounting offer a more engineering-friendly path for process changes, context isolation, failure handling, cost auditing, and external delivery.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| DeterminFlow This agent | 66 · Some gaps | Desktop appFree + model costs | ★ 927 | 1mo ago | Python | — |
| Synapse AI — Multi-Agent Orchestration Platform | 70 · Some gaps | CLIFree + model costs | ★ 331 | 1d ago | Python | OpenAI API · Claude API |
| Open Swarm | 40 · Major gaps | — | ★ 829 | 11d ago | JavaScript | Claude API |
| AgentScope 2.0 | 70 · Some gaps | Library / SDKFree + model costs | ★ 34k | 1d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: README claims per-node tool allowlists, minimal context, approval nodes, token ledgers, and checkpoints; SECURITY.md explicitly states Plugins run as trusted local code inheriting Core process permissions without sandboxing, and gives credential guidance via env vars/Secret Files; tests show token rotation and subject validation. Deductions: all claims are documentation, not visible implementation code; sandbox absence and plugin trust risk are self-acknowledged; external effects (API/DB nodes) lack code-level constraint evidence.
Evidence: all dependencies exactly pinned with lock files, Docker config check, three CI pipelines (backend/frontend/container); tests show structured error codes (version_changed, authentication_failed, 409 conflicts) and clear messages. Deductions: pyproject version is 0.1.0 while README installers say 1.1.0, an internal version inconsistency; core runtime code is absent from evidence, so failure-message quality is only inferred from tests.
Evidence: target audience (production AI workflow developers) and scenarios (novel pipeline, API service, Cron) are clearly described; environment fit covers Windows/macOS/Docker/source with executor-mode fallback, earning full marks. Deductions: trigger semantics (Cron/event inputs) are covered only in passing; capability boundaries are stated in Roadmap and security notes but per-node permission limits remain assertions.
Evidence: clean doc structure (architecture, plugin spec, extension guide), per-platform install notes with version requirements, compatibility aliases (AI_COMPANY_* → DETERMINFLOW_*) documented, honest known limitations (unsigned macOS, manual updates, no sandbox), full AGPL-3.0 text in repo, SECURITY.md with private reporting. Deductions: no CHANGELOG file, internal version contradiction (0.1.0 vs 1.1.0), single unidentified maintainer with only a release badge supporting update cadence.
Evidence: concrete feature comparison against single-agent frameworks, clear differentiated value in node-level resume and per-node billing, cost table with three scenarios. Deductions: the 70%–89% savings are author-estimated against a hypothetical single-agent baseline with no independent corroboration; no execution data validates output usability.
Evidence: README labels estimates as estimated and notes pricing timing, showing good fact/inference separation; test files corroborate documented behaviors (marketplace review, token handling, packaging verification) reasonably. Deductions: headline claims (11 sessions, 176,584 tokens, 9.1×) cannot be traced to raw ledger data in the repo; core runtime source is absent from evidence so claims cannot be checked against implementation.
- Plugins run as trusted local code with no sandbox; install only trusted sources and follow SECURITY.md advice on a dedicated run account and minimal environment variables.
- Token savings (70%–89%) are author estimates; benchmark independently before adoption.
- pyproject version (0.1.0) contradicts installer version (1.1.0); treat GitHub Releases as authoritative and verify the deployed version.
- The macOS build is ad-hoc signed and not notarized; first launch requires manual approval in Privacy & Security.
- Publisher is an unverified single maintainer; assess bus-factor and AGPL-3.0 network-service compliance obligations before enterprise use.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.1.1 DeterminFlow v1.1.1
Release notes excerpt
DeterminFlow v1.1.1 本次更新增加内置社区插件源，并同步设置分类、会话引用和插件安装确认。 新增能力 - 社区插件：内置 [DeterminFlow-Community-Plugins](https://github.com/alikon-art/DeterminFlow-Community-Plugins)，与官方插件仓库分开。进入目录只表示结构与既定检查通过，不是官方安全背书。 - 安装确认：从社区或自行添加的仓库安装插件前，会弹出同机同权限风险对话框；官方仓库仍直接安装。 - 仓库名称：官方与社区源显示为「DeterminFlow 官方插件」「DeterminFlow 社区插件」。 - 设置页按外观、模型、压缩、插件、记忆和工作区接口分栏保存。 - 输入框可用 @ 引用 Prompt、Agent、Skill、Rule、Workflow 和会话；会话侧栏支持本机置顶。 - 资源广场支持单个 Skill 的多文件包。 - Core 补齐长期记忆和工作区宿主接口。没有对应插件时，这些接口保持空闲。 修复与改进 - 插件页刷新远程目录时，不再把进行中的空结果显示成没有仓库。 安装与升级 | 平台 | Core | Full | |---|---|---| …View on GitHub ↗ -
v1.1.0 DeterminFlow v1.1.0
Release notes excerpt
DeterminFlow v1.1.0 本次更新带来资源广场、统一账号和 macOS 安装包，并改善插件分发及桌面运行稳定性。 新增能力 - 资源广场：发现、搜索、安装和分享社区 Skill，查看更新记录、管理投稿与版本；当前仅开放 Skill 分发。 - Skill 更新：Skills 页面提示可用更新并定位广场详情；更新保留运行配置，核验来源、版本和内容摘要。 - 作者发布：可以使用其他本地 Skill 维护同一线上资源，保留线上身份和历史版本。 - 统一账号：资源广场与公益模型共用登录状态，支持浏览器授权和返回桌面客户端。 - macOS：提供 Apple Silicon Core/Full 安装包，公益模型支持 macOS。 - 加速分发：安装包和官方插件支持经过完整性校验的加速下载，官方插件增加签名 HTTPS 包安装。 修复与改进 - 改善执行器并行启动，桌面启动等待上限调整为 90 秒。 - 改善重试预算、工具结果续接和任务恢复；永久模型服务错误不再无效重试。 - 修复首次引导模型目录、登录入口和公益状态异常时的重试显示。 - 修复插件更新识别、只读安装目录写入、公告确认保存及输入框和消息滚动布局。 - 修复 macOS 应用签名封装，并验证 DMG 安装副本中的后端启动。 安装与升级 | 平台 | Core | Full | …View on GitHub ↗ -
v1.0.10 DeterminFlow v1.0.10
Release notes excerpt
DeterminFlow v1.0.10 - Windows Workflow Runtime 默认使用 4 个独立 Executor 进程，支持同一 Workflow Task 及其节点重试、打回继续固定在同一 Executor，并补充进程恢复、状态观测与真实并发场景验证。 - Windows Full 安装包携带发行准备时最新且已验证的公开官方 Plugin，并以绑定桌面版本的精确 Commit 构建锁保证同版本重建不会随 main 漂移。 - Full 当前锁定 bishu-novel 0.2.2 与 public-api 0.1.33；公益模型客户端包含独立公告、余额档位和完整模型目录。Core 安装包仍不捆绑任何 Plugin。 - 首次安装引导中的匿名公益模型已更正为 auto；公告弹窗在桌面端加宽为横向布局，并保持窄屏自适应与内容滚动。 本版本不覆盖已有 Workflow、Task、Workspace、Plugin、模型配置或用户数据。Full 初始快照不依赖 Git；后续从 Plugin 页面在线更新仍需要系统可用的 Git。View on GitHub ↗