hiveflow
jdidjhdh/hiveflow
Multi-agent coordination & HITL layer — self-hosted Studio, MCP tools, LangGraph sidecar. Alpha 0.1.x
Instalação
npx convez-ai jdidjhdh/hiveflow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
0.1.x Alpha — Install via Docker, git source, or GitHub Release wheels (PyPI optional later) · versioning policy · docs · contribute (fork / edit docs / discussions)
HiveFlow is the multi-agent coordination and HITL layer for teams that need human approval, audited shared state, and a self-hosted ops UI — while staying compatible with runtimes like LangGraph via the sidecar pattern.
Why HiveFlow?
| Differentiator | What you get |
|---|---|
| Coordination layer | Scheduler, blackboard, HITL — use native runtime or LangGraph sidecar |
| Human-in-the-Loop | Plan and action gates with Studio Approvals + timeout policies |
| Visual Studio | Orchestrator, Chatflow, Analytics, Replay, HITL — self-hosted |
| Security | Dual input/output guards + audited, encryptable blackboard |
| MCP-native | Unified tool protocol and plugin marketplace hooks |
Golden Path (~5 min)
Try HiveFlow Studio in Agent mode: natural language → plan → canvas → execute. No API key required when HIVEFLOW_AGENT_ECHO_LLM=true (default in docker-compose.yml).
1. Docker (recommended)
git clone https://github.com/jdidjhdh/hiveflow.git
cd hiveflow
docker compose up --build
Open http://localhost:3000 → Orchestrator → enable Agent / real mode.
| Step | Action |
|---|---|
| 1 | Enter a goal (e.g. Summarize three trends in AI agents) |
| 2 | Click Plan only and review the TaskGraph |
| 3 | Import to canvas → Execute DAG |
APIs: POST /api/agent/plan-only · execute-plan · query — see Studio Agent cookbook (中文).
2. Library / scripts (no PyPI required)
From source (recommended for 0.1.x):
git clone https://github.com/jdidjhdh/hiveflow.git
cd hiveflow
pip install -e packages/core -e packages/agent
python examples/01_hello_hiveflow.py
Optional extras: pip install -e "packages/core[all]" (security, llm, rag, redis).
From GitHub Release wheels — download hiveflow_core / hiveflow_agent wheels from v0.1.0, then:
pip install ./hiveflow_core-*.whl ./hiveflow_agent-*.whl
PyPI (pip install hiveflow-core) will be added when published; not required for Alpha.
Advanced — embed Core engine only
For low-level control without Studio: register agents, schedule ECM tasks, read the blackboard.
import asyncio
from hiveflow import HiveFlow, HiveFlowConfig, ECM
async def main():
hf = HiveFlow(HiveFlowConfig())
await hf.start()
try:
async def handler(ecm, view):
await view.put("result", f"Done: {ecm.intent}")
return {"status": "ok"}
await hf.create_agent(
agent_id="worker",
skills={"process"},
read_keys=set(),
write_keys={"result"},
task_handler=handler,
)
await hf.scheduler.schedule(ECM(
trace_id="demo-1",
intent="Research AI trends",
intent_id="task-1",
emitter="user",
required_skills=["process"],
))
await asyncio.sleep(0.5)
print(await hf.blackboard.sys_get("result"))
finally:
await hf.shutdown()
asyncio.run(main())
→ examples/01_hello_hiveflow.py · Core README
Features
| Area | Capabilities |
|---|---|
| Orchestration | Static/dynamic DAG, cognitive planning, 3 scheduler strategies |
| Collaboration | Event bus, skill-based routing, multi-agent blackboard |
| HITL | Approval gates, plan review, Studio + WebSocket notifications |
| Data | RAG pipeline, checkpoints (time travel), streaming SSE |
| Tools | MCP protocol, plugin marketplace, ReAct workers |
| Ops | Studio UI, Prometheus analytics, trace replay |
Architecture
┌─────────────────────────────────────────────────────────────┐
│ HiveFlow Studio (Web UI) │
└─────────────────────────────┬───────────────────────────────┘
│ REST + WebSocket
┌─────────────────────────────▼───────────────────────────────┐
│ HiveFlow Agent Runtime │
└─────────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────┐
│ HiveFlow Core (scheduler, HITL, RAG, MCP) │
└─────────────────────────────────────────────────────────────┘
Details: Architecture (EN) · 架构 (ZH)
Three modules
HiveFlow is a monorepo with three packages. Pick the layer that matches your integration depth.
| Module | Package | Role | Typical user |
|---|---|---|---|
| Core | hiveflow · source / Release | Orchestration kernel — scheduler, blackboard, DAG/HITL/RAG/MCP | Library authors, backend engineers |
| Agent | hiveflow-agent · source / Release | NL planning + cognitive Skill graphs on top of Core | Agent builders, LLM app developers |
| Studio | packages/studio · self-hosted | Visual ops UI + FastAPI backend (REST/WS) | Operators, reviewers, full-stack teams |
Core — packages/core (hiveflow)
The embeddable engine. You register workers with skills, schedule ECM tasks, and coordinate through a shared blackboard. Includes static/dynamic DAG orchestrators, HITL gates, checkpoints, dual guards, RAG, MCP plugin hooks, and Prometheus-friendly metrics — with no UI dependency.
- Install:
pip install -e packages/coreor Release wheels · Docs: Core README · API - Examples:
examples/01_hello_hiveflow.py…15_multimodal_pipeline.py
Agent — packages/agent (hiveflow-agent)
The cognitive runtime on Core. HiveMindApp turns natural language into a TaskGraph, binds Skills to ReAct workers, and executes via CognitiveOrchestrator. Supports plan-only, full run_query, and execute_plan on an existing graph — with optional plan HITL before execution.
- Install:
pip install -e packages/agentor Release wheels · Docs: Agent README · Studio Agent cookbook - Key APIs:
run_query·plan_only·execute_plan(also exposed as/api/agent/*in Studio)
Studio — packages/studio (FastAPI + React)
The visual operations platform. Orchestrator and Chatflow for workflow design; Approvals for HITL; Analytics, Tracer, and Replay for observability. The backend bridges Core DAG execution and Agent mode (HIVEFLOW_RUNTIME=agent), including LangGraph plan export.
- Run locally:
docker compose upor backenduvicorn+ frontendnpm run dev - Production images: tagged GHCR images on
v*releases — seedocker-compose.release.yml - Feature maturity: CAPABILITIES.md (Stable / Beta / Preview / Demo per page)
- Docs: Studio README · Agent ops guide
v0.1.x preview: Studio has no built-in login. Deploy behind VPN or a reverse proxy. Electron desktop scripts are experimental and not part of release artifacts.
Documentation
| Resource | English | 中文 |
|---|---|---|
| Documentation site | English | zh/ |
| Getting Started | docs/en/getting-started.md | docs/zh/getting-started.md |
| Three modules | Core · Agent · Studio | Core · Agent · Studio |
| Cookbook | docs/en/cookbook/ | docs/zh/cookbook/ |
| OSS launch | OSS_LAUNCH.md | docs/zh/oss-launch.md |
Project structure
HiveFlow/
├── packages/core/ # hiveflow-core — orchestration kernel (source / Release)
├── packages/agent/ # hiveflow-agent — NL cognitive runtime (source / Release)
├── packages/studio/ # Self-hosted UI + FastAPI backend
├── examples/ # 16 smoke-tested examples
└── docs/ # MkDocs(en/ + zh/)
See Three modules above for what each layer does and when to use it.
Development
# Core tests
cd packages/core && pip install -e ".[dev]" && pytest
# Studio backend
cd packages/studio/backend && pip install -r requirements.txt -r requirements-dev.txt
HIVEFLOW_AGENT_ECHO_LLM=true pytest tests/
# Frontend
cd packages/studio/frontend && npm ci && npm run lint && npm run test:unit && npm run build
# Docs
pip install mkdocs-material "mkdocstrings[python]" mkdocs-static-i18n && pip install -e packages/core
python -m mkdocs build --strict
See CONTRIBUTING.md and GOVERNANCE.md.
Comparison
| Feature | HiveFlow | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|
| Dynamic orchestration | ✅ | ⚠️ | ❌ | ⚠️ |
| Human-in-the-Loop | ✅ | ⚠️ | ❌ | ⚠️ |
| Checkpoint / replay | ✅ | ✅ | ❌ | ❌ |
| Security guards | ✅ | ❌ | ❌ | ❌ |
| MCP protocol | ✅ | ❌ | ❌ | ❌ |
| Visual ops UI | ✅ | 💰 | ❌ | ❌ |
✅ Built-in · ⚠️ Custom · ❌ N/A · 💰 Paid product
Maintainers
HiveFlow is maintained by the core team. Interested in helping? See CONTRIBUTING.md.
License
MIT — see LICENSE.
Acknowledgments
Inspired by LangGraph, CrewAI, and AutoGen · Built on MCP · Studio UI uses Ant Design and React