LangGraph + HiveFlow Sidecar¶
在 LangGraph(或任意图运行时)中执行节点,由 HiveFlow 提供多 Agent 协调层:HITL 门控、可审计黑板、Guard 与 Studio 运维界面。
状态: Sidecar 模式现已支持(导出 + Studio HITL API)。进程内 LangGraph 执行(
LangGraphExecutionBackend.execute())为 v0.3 占位 — 当前请用导出 + 外部运行时。
适用场景¶
- 团队已标准化使用 LangGraph 跑图
- 需要非工程师审批(Studio Approvals)、审计/回放或加密黑板,而不想在 LangGraph 里重写 interrupt
- 希望 Studio 画布、Agent
plan-only与 LangGraph 代码生成共用同一 TaskGraph 格式
架构¶
flowchart TB
subgraph hiveflow [HiveFlow 协调层]
Studio[Studio UI]
HITL[HITLManager /api/hitl]
BB[SecureBlackboard 审计]
Guards[输入/输出 Guard]
end
subgraph external [你的 LangGraph 应用]
LG[LangGraph StateGraph]
Nodes[Agent 节点 / 工具]
end
Plan[TaskGraph JSON] -->|导出| LGSpec[LangGraph spec]
LGSpec --> LG
LG -->|interrupt_before| HITL
HITL -->|批准/拒绝| LG
Nodes -->|写入草稿| BB
Studio --> HITL
Studio --> BB
Guards --> Nodes
此模式下 HiveFlow 不替代 LangGraph — 作为多 Agent 问题的协调与 HITL 层与之并存。
步骤 1 — 在 HiveFlow 中规划(可选)¶
使用 Agent plan-only 或 Studio Orchestrator Agent 抽屉:
curl -X POST http://localhost:8000/api/agent/plan-only \
-H "Content-Type: application/json" \
-d '{"query": "调研 AI 监管,撰写摘要,合规审核"}'
返回 TaskGraph(示例):
{
"research": {"task": "search", "depends_on": []},
"draft": {"task": "write", "depends_on": ["research"]},
"compliance": {
"task": "review",
"depends_on": ["draft"],
"hitl": {"action": "approval", "prompt": "发布前是否批准?"}
},
"final_answer": {"task": "summarize", "depends_on": ["compliance"]}
}
步骤 2 — 导出为 LangGraph 规格¶
Python(Core)¶
from hiveflow.execution import LangGraphExecutionBackend
backend = LangGraphExecutionBackend()
spec = backend.to_langgraph_spec(plan, workflow_id="content_pipeline")
# spec["interrupt_before"] 含 HITL 节点(如 "compliance")
或直接使用适配器:
from hiveflow.adapters.langgraph import taskgraph_to_langgraph, render_langgraph_python
spec = taskgraph_to_langgraph(plan)
python_stub = render_langgraph_python(spec, graph_name="content_graph")
Studio API¶
curl -X POST http://localhost:8000/api/agent/export-langgraph \
-H "Content-Type: application/json" \
-d '{"plan": {...}, "workflow_id": "content_pipeline", "include_python": true}'
Orchestrator 工具栏 导出 LangGraph 可直接导出画布,无需 plan-only。
步骤 3 — 在外部运行 LangGraph¶
按常规方式实现 LangGraph 图(pip install langgraph langchain-core)。将 HiveFlow skill 名(search、write …)映射到 LangGraph 节点。
当 LangGraph 触发 interrupt_before(来自导出规格)时,暂停并调用 HiveFlow,而非自建 Flask 审批页。
步骤 4 — 经 HiveFlow 接入 HITL(Sidecar)¶
创建门控(库)¶
在 LangGraph interrupt 处理器或薄 FastAPI sidecar 中:
from hiveflow import HITLManager, HITLAction, SecureBlackboard
bb = SecureBlackboard()
hitl = HITLManager(bb)
gate = await hitl.create_gate(
workflow_id="content_pipeline",
node_id="compliance",
action=HITLAction.APPROVAL,
prompt="发布前是否批准草稿?",
context={"draft": draft_text, "intent_id": trace_id},
timeout_seconds=3600,
)
经 Studio API 响应¶
审批人使用 Studio → 审批,或自动化调用:
curl http://localhost:8000/api/hitl/pending
curl -X POST http://localhost:8000/api/hitl/{gate_id}/respond \
-H "Content-Type: application/json" \
-d '{"approved": true, "comment": "同意"}'
仅在门控批准后恢复 LangGraph。
审计与回放¶
- 将 Agent 输出写入
SecureBlackboard,键按intent_id隔离 - Studio Replay / Tracer 使用相同
intent_id/trace_id - 见 合规 HITL 案例
步骤 5 — 在代码中选择 ExecutionBackend¶
from hiveflow import SecureBlackboard
from hiveflow.execution import get_execution_backend, LangGraphExecutionBackend
from hiveflow.orchestrator import DynamicOrchestrator
bb = SecureBlackboard()
native = get_execution_backend("native", orchestrator=DynamicOrchestrator(bb))
# 完整 HiveFlow 运行时(不用 LangGraph)
result = await native.execute(executable_graph, global_timeout=120.0)
# LangGraph:当前仅导出
lg = LangGraphExecutionBackend()
spec = lg.to_langgraph_spec(skill_plan)
# await lg.execute(...) → ExecutionBackendNotReadyError,v0.3 桥接后可用
| 后端 | execute() |
Sidecar 导出 |
|---|---|---|
native |
✅ DynamicOrchestrator | — |
langgraph |
❌ 占位(v0.3) | ✅ to_langgraph_spec() |
ExecutionBackend 参考¶
GraphExecutionResult:backend、results、status、metadataNativeExecutionBackend:生产默认LangGraphExecutionBackend:导出 + 未来进程内桥接
测试:packages/core/tests/test_execution_backend.py
限制(0.1.x)¶
| 能力 | Sidecar 现状 | 进程内 LangGraph |
|---|---|---|
| 拓扑 / depends_on | ✅ 导出 | v0.3 计划 |
| HITL → interrupt_before | ✅ | 计划中 |
| 条件边 | ❌ | ❌ |
| Checkpoint 元数据往返 | ❌ | ❌ |
| LangChain Tool 桥 | 用 MCP | 计划中 |