Part 1 — Foundation¶
Install HiveFlow, understand the repository layout, and run your first workflow.
1.1 Installation paths¶
Path A — Docker (recommended for Studio)¶
git clone https://github.com/jdidjhdh/hiveflow.git
cd hiveflow
cp .env.example .env # optional: set API keys
docker compose up --build
| Service | URL |
|---|---|
| Studio UI | http://localhost:3000 |
| API | http://localhost:8000 |
| Redis | localhost:6379 |
| Postgres | localhost:5432 |
Default docker-compose.yml sets HIVEFLOW_AGENT_ECHO_LLM=true so you can use Agent mode without an LLM API key.
Path B — PyPI (library only)¶
pip install hiveflow-core hiveflow-agent
Optional extras:
pip install "hiveflow-core[security]" # encryption, JSON schema
pip install "hiveflow-core[llm]" # OpenAI + Anthropic
pip install "hiveflow-core[rag]" # RAG utilities
pip install "hiveflow-core[all]" # everything
Path C — Editable source (contributors)¶
git clone https://github.com/jdidjhdh/hiveflow.git
cd hiveflow
pip install -e packages/core -e packages/agent
pip install -e "packages/core[all]"
1.2 Repository layout¶
hiveflow/
├── packages/core/ # Orchestration kernel (hiveflow-core)
├── packages/agent/ # NL planning + LLM (hiveflow-agent)
├── packages/studio/ # FastAPI backend + React frontend
├── examples/ # 16 runnable tutorials
├── docs/ # MkDocs (en/ + zh/)
├── scripts/ # Release, CI, debug utilities
├── docker-compose.yml # Full local stack
└── kubernetes/ # K8s deployment manifest
Three layers:
| Layer | Package | Role |
|---|---|---|
| Core | hiveflow-core |
Scheduler, blackboard, DAG, HITL, MCP — no UI |
| Agent | hiveflow-agent |
Natural-language planning, ReAct worker, LLM routing |
| Studio | packages/studio |
Visual ops UI on top of Core + Agent |
1.3 Core concepts (minimal)¶
Before coding, know these four primitives:
| Primitive | Purpose |
|---|---|
| ECM | Event-Condition-Message — a unit of work sent to the scheduler |
| Cell / Agent | Worker with skills, read/write keys, and a task_handler |
| Blackboard | Shared key-value store between agents |
| Scheduler | Routes ECM to agents by required skills |
See Concepts for full definitions.
1.4 Your first workflow (Example 01)¶
Create hello.py or run the built-in example:
python examples/01_hello_hiveflow.py
Expected output:
Task scheduled: True
Workflow completed!
Result: Hello from user! Task: Say hello to the world
Step-by-step¶
import asyncio
from hiveflow import HiveFlow, HiveFlowConfig, ECM
async def main():
hf = HiveFlow(HiveFlowConfig())
await hf.start()
try:
async def greet_handler(ecm, view):
message = f"Hello from {ecm.emitter}! Task: {ecm.intent}"
await view.put("greeting_result", message)
return {"message": message}
await hf.create_agent(
agent_id="greeter",
skills={"greet", "respond"},
read_keys=set(),
write_keys={"greeting_result"},
task_handler=greet_handler,
)
ecm = ECM(
trace_id="hello-1",
intent="Say hello to the world",
intent_id="intent-1",
emitter="user",
required_skills=["greet"],
payload={"message": "Hello"},
)
await hf.scheduler.schedule(ecm)
await asyncio.sleep(0.5)
print(await hf.blackboard.sys_get("greeting_result"))
finally:
await hf.shutdown()
asyncio.run(main())
What happens internally¶
HiveFlow.start()boots the event bus, scheduler, and blackboard.create_agent()registers a Cell with skills and ACL keys.scheduler.schedule(ecm)picks the greeter (only agent withgreetskill).- The handler writes to the blackboard via
view.put(). shutdown()drains queues and closes connections.
1.5 Configuration basics¶
Copy environment template:
cp .env.example .env
Programmatic config:
from hiveflow import HiveFlowConfig, SchedulerConfig
config = HiveFlowConfig(
scheduler=SchedulerConfig(
selection_strategy="least_loaded", # or "auction", "load_aware"
default_intent_timeout=60.0,
),
blackboard_type="memory", # memory | ttl_memory | redis | encrypted
log_level="INFO",
)
1.6 Exercises¶
- Add a second agent with skill
respondthat readsgreeting_resultand writesfinal_reply. - Change
selection_strategyto"auction"and observe logs. - Set
blackboard_type="ttl_memory"and inspect TTL behavior in Part 3.
Next¶
→ Part 2 — Workflows: multi-agent pipelines, HITL, streaming, RAG.