Fusion Agent Framework

Build agent workflows with privacy routing, RAG, and observability.

A 13-node canvas, DSL orchestration, and a six-layer runtime. Open source. Self-hosted.

What is Hanflow?

A fusion AI orchestration framework that combines the best of workflow engines and autonomous agents — like a hybrid car that runs on pure electric, pure gas, or both.

Hanflow (Harmony AI Nexus) is a high-control, YAML-driven agent framework built on LangGraph. It treats privacy-aware model routing, RAG retrieval, human-in-the-loop approval, and full-chain observability as first-class citizens — not afterthoughts.

In a world where autonomous AI agents are becoming mainstream, deterministic workflow orchestration still holds irreplaceable value for SOP-driven scenarios. Hanflow does not force you to choose: it supports pure static workflows (Dify-style), pure dynamic agents (DeerFlow-style), and hybrid compositions — all from a single unified DSL, with no mode switch.

The framework is designed for self-evolution: a Loop-driven system automatically discovers improvement opportunities, plans iterations, implements with TDD, and releases new versions — with human approval at every critical gate. Open source, Apache-2.0, built to last.

Six-Layer Architecture

L1 Delivery

CLI / Web Studio / SDK

Three entry points: command-line, visual canvas, and Python SDK.

L2 Orchestration

YAML DSL → LangGraph

YAML workflow DSL compiles to LangGraph StateGraph. 13 primitive node types with recursive static/dynamic composition.

L3 Capabilities

Research / Execution Atoms

Pluggable Research and Execution atoms. Citation-proven deep research and file-system-as-memory task execution.

L4 Foundation

ModelRouter / MCPBus / RAG

ModelRouter with 6 strategies including privacy routing. MCPBus for unified tool access. Multi-backend RAG retrieval.

L5 Persistence

Checkpoint / Session / Artifact

Checkpoint, session, and artifact stores with crash recovery and time-travel resume.

L6 Observability

LangSmith / OTel Trace

Cross-cutting trace, eval, and monitoring via LangSmith or OpenTelemetry. One-line enable.

The only framework that, under a unified DSL, supports recursive static/dynamic composition — with privacy routing, RAG, HITL, and LangSmith observability as first-class citizens.

Capabilities

Everything you need to ship agents.

13-node canvas

Compose Sequential, Parallel, Loop, Branch, HITL, LLM, Tool, Research, Execution, Coordinator, Memory, Subworkflow, and Knowledge nodes.

DSL orchestration

Declarative YAML with depends_on, conditions, retries, and per-node error policies. Acyclic DAG, compiled and validated.

Privacy routing

Sensitivity tiers and PII detection route regulated workloads to local models. Hard or soft enforcement.

MCP tool bus

A unified bus over stdio, sse, http, websocket, and in-process transports, with rate limiting and destructive guards.

RAG retrieval

Vector, fulltext, and hybrid search with RRF, weighted, and cascade fusion. Pluggable embeddings and rerankers.

Web Studio

Build, Monitor, and HITL modes. A live canvas, trace timeline, and approval panel with countdown.

Architecture

Six layers, one runtime.

L1 DeliveryREST, WebSocket, Webhooks
L2 OrchestrationCompiler, registry, executors
L3 CapabilitiesAtoms: research, execution
L4 FoundationModels, tools, retrieval, memory
L5 PersistenceCheckpoint, session, artifact
L6 ObservabilityTrace, metrics, logs

L1 Delivery

L2 Orchestration

L3 Capabilities

L4 Foundation

L5 Persistence

L6 Observability

Quick Demo

Running in three steps.

Clone

Get the repo and copy the example config.

git clone https://github.com/xpc1024/hanflow && cd hanflow

Configure

Set your model keys in .env.

cp deploy/docker/hanflow.yaml.example hanflow.yaml
cp deploy/docker/.env.example .env

03
Run
Bring up the full stack with one command.
```
cd deploy/docker && docker compose up -d
```

Start building.

Install

docker compose up -d

Start building.