HiveFlow 快速入门¶
本指南将帮助你在几分钟内上手 HiveFlow。
Golden Path — Studio Agent 模式¶
最快体验 HiveFlow 的方式:启动 Studio + Agent 运行时,用自然语言生成计划,导入画布并执行。
Docker(推荐)¶
git clone https://github.com/jdidjhdh/hiveflow.git
cd hiveflow
docker compose up --build
打开 http://localhost:3000 → Orchestrator(编排器) → 开启 Agent / real mode → Plan only → 导入到画布 → 执行 DAG。
详见 Studio Agent 指南。
PyPI 快速验证¶
pip install hiveflow-core hiveflow-agent
python examples/01_hello_hiveflow.py
前置条件¶
- Python 3.10+
- pip
- (可选)Redis — 分布式黑板与事件总线
- (可选)Node.js 18+ — Studio 前端开发
安装¶
从 PyPI 安装¶
pip install hiveflow-core # core
pip install "hiveflow-core[security]" # encryption + JSON schema
pip install "hiveflow-core[llm]" # OpenAI + Anthropic clients
pip install "hiveflow-core[rag]" # RAG utilities
pip install "hiveflow-core[all]" # all optional extras
从源码安装¶
git clone https://github.com/jdidjhdh/hiveflow.git
cd hiveflow/packages/core
pip install -e ".[dev]"
快速开始¶
HiveFlow 是一个底层编排引擎。你需要创建带任务处理器的 Agent,使用 ECM 消息调度工作,并从共享黑板读取结果。
1. Hello HiveFlow¶
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! Task: {ecm.intent}"
await view.put("greeting_result", message)
return {"message": message}
await hf.create_agent(
agent_id="greeter",
skills={"greet"},
read_keys=set(),
write_keys={"greeting_result"},
task_handler=greet_handler,
)
ecm = ECM(
trace_id="hello-1",
intent="Say hello",
intent_id="intent-1",
emitter="user",
required_skills=["greet"],
payload={"message": "Hello"},
)
await hf.scheduler.schedule(ecm)
await asyncio.sleep(0.5)
result = await hf.blackboard.sys_get("greeting_result")
print(result)
finally:
await hf.shutdown()
asyncio.run(main())
可运行示例: python examples/01_hello_hiveflow.py
2. 多智能体协作¶
将中间结果写入黑板并调度后续任务,即可串联多个 Agent。参见 examples/02_multi_agent.py。
3. Human-in-the-Loop(人机协同)¶
使用 HITLManager 暂停工作流,直到人工审批:
from hiveflow import HITLManager, HITLAction
hitl = HITLManager()
gate = await hitl.create_gate(
workflow_id="wf-1",
node_id="review",
action=HITLAction.APPROVAL,
prompt="Approve this output?",
context={"draft": "..."},
)
await hitl.respond(gate.gate_id, approved=True, comment="LGTM")
可运行示例: python examples/03_hitl_approval.py
4. 流式事件¶
使用 StreamBuffer 发送类型化事件(token、工具调用、节点生命周期):
from hiveflow import StreamBuffer, StreamEvent, StreamEventType, collect_stream
buffer = StreamBuffer()
await buffer.put(StreamEvent(type=StreamEventType.TOKEN, data="Hello"))
await buffer.put(StreamEvent(type=StreamEventType.DONE, data=None))
await buffer.close()
events = await collect_stream(buffer)
可运行示例: python examples/05_streaming.py
示例 Cookbook¶
| 示例 | 主题 |
|---|---|
01_hello_hiveflow.py |
第一个工作流 |
02_multi_agent.py |
多智能体流水线 |
03_hitl_approval.py |
人工审批 |
04_checkpoint.py |
检查点与时间旅行 |
05_streaming.py |
流式事件 |
06_rag_pipeline.py |
RAG 流水线 |
07_mcp_tools.py |
MCP 工具集成 |
08_cognitive_planning.py |
认知编排器 |
09_evaluation.py |
评估与 A/B 测试 |
10_secure_blackboard.py |
加密黑板 |
11_distributed_agents.py |
Redis 部署 |
12_custom_scheduler.py |
自定义调度策略 |
13_plugin_development.py |
插件市场 |
14_guard_configuration.py |
输入/输出守卫 |
15_multimodal_pipeline.py |
图像/音频/视频处理 |
从仓库根目录运行任意示例:
cd packages/core && pip install -e ".[all]"
cd ../../examples && python 01_hello_hiveflow.py
配置¶
复制环境变量模板:
cp .env.example .env
编程式配置¶
from hiveflow import HiveFlowConfig, SchedulerConfig
config = HiveFlowConfig(
scheduler=SchedulerConfig(
selection_strategy="least_loaded",
default_intent_timeout=60.0,
),
blackboard_type="memory", # memory | ttl_memory | redis | encrypted
worker_max_queue_size=100,
log_level="INFO",
)
Redis(分布式)¶
config = HiveFlowConfig(
blackboard_type="redis",
redis_url="redis://localhost:6379",
)
docker run -d -p 6379:6379 redis:7-alpine
下一步¶
故障排查¶
No module named 'hiveflow' — 在 packages/core 目录下使用 pip install -e ".[dev]" 从源码安装。
可选功能 ImportError — 安装对应的 extra,例如 pip install "hiveflow-core[security]"。
Redis 连接错误 — 确保 Redis 正在运行(redis-cli ping → PONG)。
Studio Agent 模式¶
HiveFlow Studio 可在 Core DAG 与 HiveMind Agent 两种运行时之间切换。Agent 模式使用 HiveMindApp.run_query 自动规划 Skill 图;开启计划 HITL 后,执行前需在「人工审批」页审阅计划 JSON。
环境变量¶
| 变量 | 说明 |
|---|---|
HIVEFLOW_RUNTIME=agent |
启动时默认 Agent 模式 |
HIVEFLOW_PLAN_HITL=true |
执行前需人工审批计划图 |
HIVEFLOW_AGENT_ECHO_LLM=true |
无 LLM 时使用 Echo 客户端(测试/联调) |
HIVEFLOW_LLM_PLANNING_PROVIDER |
规划阶段 LLM 路由 |
HIVEFLOW_LLM_EXECUTION_PROVIDER |
执行阶段 LLM 路由 |
本地启动¶
# 后端(packages/studio/backend)
pip install -r requirements.txt
$env:HIVEFLOW_RUNTIME="agent"
$env:HIVEFLOW_PLAN_HITL="true"
$env:HIVEFLOW_AGENT_ECHO_LLM="true"
uvicorn app.main:app --reload --port 8000
# 前端(packages/studio/frontend)
npm install && npm run dev
在 Studio 顶栏打开真实模式,编排器内切换 Agent 模式,使用「Agent 查询」或「NL 生成草图(plan-only)」。
相关页面¶
- 人工审批 — 审阅/编辑
plan_approval计划 JSON - 执行分析 — 真实模式下读取
/api/analytics/* - 执行回放 — 按
intent_id查看 audit 与 checkpoint - 任务追踪 — 实时 WS 事件,
intent_id与trace_id已统一
详见 Studio Agent 运维 与 完整教程 — 第 5 部分。