Ecosystem Compatibility Guide¶
LangChain · LangGraph · MCP · OpenAI / Anthropic
This guide explains how HiveFlow interoperates with mainstream AI agent frameworks — and where HiveFlow adds value that those stacks typically require custom code for.
Positioning: HiveFlow is a multi-agent coordination & HITL layer, not a drop-in replacement for LangChain. The recommended pattern is Sidecar: LangGraph (or your runtime) executes graphs; HiveFlow provides approval gates, audited shared state, guards, and Studio ops UI.
Why HiveFlow alongside LangChain?¶
LangGraph, CrewAI, and AutoGen excel at graph execution and agent loops. Teams still rebuild the same cross-cutting concerns:
| Concern | Typical LangGraph/CrewAI approach | HiveFlow |
|---|---|---|
| Human approval before side effects | Custom interrupt() + bespoke UI |
Native HITLManager + Studio Approvals |
| Shared state between agents | Graph state dict | SecureBlackboard (memory / Redis / encrypted) |
| Audit & compliance replay | LangSmith (paid) or DIY logging | Studio Replay + Audit Log + checkpoints |
| Prompt injection / output validation | DIY middleware | Built-in Guards |
| Tool protocol | LangChain Tools | MCP-first plugin marketplace |
| Visual ops for non-engineers | LangGraph Studio (paid) or none | Self-hosted Studio (Orchestrator, Tracer, Analytics) |
| One plan format for NL → canvas → export | Multiple formats | TaskGraph JSON → Studio canvas → LangGraph spec |
HiveFlow is inspired by LangGraph, CrewAI, and AutoGen — it fills the coordination & governance gap while letting you keep your preferred execution engine.
Compatibility matrix (v0.1.x Alpha)¶
| Ecosystem piece | Status | How |
|---|---|---|
| LangGraph topology export/import | ✅ PoC | hiveflow.adapters.langgraph |
LangGraph in-process execute() |
❌ stub (v0.3) | Use Sidecar export |
| LangChain Tools / Chains | ⚠️ manual wrap | Register as ReActTool or MCP plugin |
| LangChain LLM wrappers | ⚠️ not required | HiveFlow native LLMClient (OpenAI, Anthropic, Ollama, DeepSeek) |
| OpenAI / Anthropic APIs | ✅ native | packages/agent/llm/ + Core llm_client.py |
| MCP tools | ✅ first-class | MCPPluginManager, Studio Capability Market |
| CrewAI / AutoGen / LlamaIndex | ❌ no official adapter | Sidecar or custom ExecutionBackend |
| LangSmith traces | ⚠️ partial substitute | Studio Tracer / Replay; OpenTelemetry optional |
See LangGraph integration and roadmap (v0.3 adapter hardening).
Architecture diagrams & explanations¶
This section pairs every diagram element with text so you can read the picture top-to-bottom without opening source code.
Figure 1 — Coordination layer vs execution layer¶
What this figure shows: HiveFlow sits beside LangChain/LangGraph — not inside it. The upper box is governance & ops; the lower box is where graphs and agents actually run.
flowchart TB
subgraph hf [HiveFlow — coordination layer]
direction TB
S[Studio UI]
H[HITLManager]
B[SecureBlackboard]
G[Input/Output Guards]
M[MCP Plugin Manager]
end
subgraph rt [Your runtime — execution layer]
LG[LangGraph StateGraph]
LC[LangChain agents / tools]
LLM[OpenAI / Anthropic / Ollama]
end
S --> H
S --> B
Plan[TaskGraph JSON] -->|export| LG
LG -->|interrupt_before| H
H -->|approve| LG
LC --> LLM
LG --> M
G --> LC
B --> LG
Coordination layer — component guide¶
| # | Box | What it does | HiveFlow differentiator | LangGraph / LangChain equivalent |
|---|---|---|---|---|
| 1 | Studio UI | Web ops console: Orchestrator canvas, Approvals, Blackboard viewer, Tracer, Replay, Analytics | Self-hosted, no per-seat SaaS; non-engineers approve plans | LangGraph Studio (paid) or custom Flask admin |
| 2 | HITLManager | Creates approval gates, tracks pending/approved/rejected, supports timeouts | Native API + Studio Approvals page; maps to interrupt_before on export |
interrupt() + you build the UI |
| 3 | SecureBlackboard | Shared key-value store between agents with ACL keys | Memory / Redis / AES encrypted backends + audit log | Graph state dict only |
| 4 | Input/Output Guards | Blocks prompt injection patterns; validates output size/schema | Built-in defense-in-depth before tools execute | DIY middleware on chains |
| 5 | MCP Plugin Manager | Discovers, installs, invokes MCP tools (filesystem, HTTP, code exec, …) | MCP-first marketplace in Studio | LangChain @tool / StructuredTool classes |
Execution layer — component guide¶
| # | Box | What it does | Who implements it |
|---|---|---|---|
| 6 | LangGraph StateGraph | Compiles nodes & edges, runs checkpointer, pauses at interrupts | Your LangGraph app (Sidecar) or HiveFlow native orchestrator (no LangGraph) |
| 7 | LangChain agents / tools | ReAct loops, chains, retrievers, custom @tool functions |
Your existing LangChain code — wrap into MCP/ReActTool if needed |
| 8 | OpenAI / Anthropic / Ollama | LLM inference | HiveFlow native clients or LangChain LLM wrappers — same API keys |
Arrows — data & control flows¶
| Arrow | Meaning | Payload / trigger | Typical API or code |
|---|---|---|---|
| Studio → HITLManager | Reviewer opens Approvals, approves/rejects a gate | gate_id, approved, comment |
POST /api/hitl/{id}/respond |
| Studio → SecureBlackboard | Ops user inspects live shared keys during a run | intent_id, blackboard keys |
GET /api/blackboard/* |
| TaskGraph JSON → LangGraph | Export plan topology + HITL hints | JSON plan → LangGraph spec with interrupt_before |
taskgraph_to_langgraph() · POST /api/agent/export-langgraph |
| LangGraph → HITLManager | Graph pauses at human node; Sidecar creates a gate | node_id, draft context, trace_id |
Your interrupt handler calls hitl.create_gate() |
| HITLManager → LangGraph | Human approved; graph resumes | approved=True |
Poll gate status or webhook, then graph.invoke(...) |
| LangChain → LLM | Model call inside your agent loop | messages, tools | LangChain or HiveFlow LLMClient |
| LangGraph → MCP | Node invokes a unified tool | tool name + args | MCPPluginManager.invoke() |
| Guards → LangChain | Sanitize I/O before/after chain execution | text in/out | Guards.validate_input() / validate_output() |
| Blackboard → LangGraph | Node reads/writes audited shared state | key-value by intent_id |
blackboard.sys_get/put() from node code |
Division of responsibility:
- HiveFlow owns: NL → TaskGraph planning surface, human gates, encrypted audited blackboard, guards, self-hosted ops UI, MCP catalog.
- Your runtime owns: node functions, LangChain chains, tool bodies, LangGraph checkpointers (until v0.3 in-process bridge).
→ Deeper system design: Architecture
Figure 2 — HiveFlow native three-layer stack¶
What this figure shows: When you run full HiveFlow (Path 1), components stack vertically. This is HiveFlow's internal architecture — independent of LangGraph.
┌─────────────────────────────────────────────────────────────┐
│ Layer 3 — HiveFlow Studio (React + FastAPI) │
│ Orchestrator · Chatflow · Approvals · Tracer · Analytics │
└─────────────────────────────┬───────────────────────────────┘
│ REST + WebSocket (SSE)
┌─────────────────────────────▼───────────────────────────────┐
│ Layer 2 — HiveFlow Agent Runtime (hiveflow-agent) │
│ NL planning · ReActWorker · LLM routing · memory · tools │
└─────────────────────────────┬───────────────────────────────┘
│ ECM messages · scheduler calls
┌─────────────────────────────▼───────────────────────────────┐
│ Layer 1 — HiveFlow Core Engine (hiveflow-core) │
│ Event Bus · Scheduler · Cell · Blackboard · HITL · MCP │
└─────────────────────────────────────────────────────────────┘
Layer guide¶
| Layer | Package | Key modules | Role in compatibility story |
|---|---|---|---|
| Layer 3 — Studio | packages/studio |
Orchestrator, /api/agent/*, /api/hitl/* |
Where reviewers approve plans; where you export LangGraph JSON from the UI |
| Layer 2 — Agent | packages/agent |
HiveMindApp, ReActWorker, llm/* |
NL → TaskGraph; wraps Core without requiring LangChain |
| Layer 1 — Core | packages/core |
HiveFlow, HITLManager, adapters/langgraph |
Scheduling, blackboard, HITL primitives, LangGraph export adapter |
How this relates to Figure 1: Layers 1–3 together form the HiveFlow coordination box. In Sidecar mode, Layer 2 planning still produces TaskGraph JSON, but execution happens in your external LangGraph process instead of Core's native orchestrator.
Figure 3 — Sidecar lifecycle (sequence)¶
What this figure shows: One full Sidecar iteration — from natural-language plan to human approval to resumed execution.
sequenceDiagram
participant U as User / Reviewer
participant ST as Studio UI
participant HF as HiveFlow API
participant BB as SecureBlackboard
participant LG as LangGraph app
U->>ST: Enter goal (Agent mode)
ST->>HF: POST /api/agent/plan-only
HF-->>ST: TaskGraph JSON + intent_id
U->>ST: Review plan (optional HITL)
ST->>HF: POST /api/agent/export-langgraph
HF-->>LG: LangGraph spec (interrupt_before)
LG->>LG: Run nodes (research, draft, …)
LG->>HF: create_gate(compliance node)
HF->>BB: Store draft + audit entry
HF-->>ST: Pending gate (Approvals)
U->>ST: Approve / reject
ST->>HF: POST /api/hitl/{id}/respond
HF-->>LG: approved=True
LG->>LG: Resume graph → final_answer
LG->>BB: Write final results
U->>ST: Replay / Tracer (same intent_id)
Sequence step guide¶
| Step | Actor | Action | HiveFlow highlight |
|---|---|---|---|
| 1 | User | Types a goal in Orchestrator Agent drawer | NL → structured TaskGraph without writing LangGraph code first |
| 2 | Studio | plan-only |
Produces reviewable JSON; optional HIVEFLOW_PLAN_HITL gate before any execution |
| 3 | User | Reviews topology on canvas | Visual ops — not available in raw LangGraph CLI |
| 4 | Export | export-langgraph |
Single format bridges Studio ↔ LangGraph team |
| 5 | LangGraph | Runs automated nodes | Your existing investment stays |
| 6 | LangGraph → HiveFlow | Interrupt handler calls create_gate |
Replaces custom approval microservice |
| 7 | Blackboard | Stores draft + audit | Encrypted, keyed by intent_id for compliance |
| 8 | Reviewer | Studio Approvals | Non-engineer friendly; same UX as native HiveFlow HITL |
| 9 | Resume | After respond(approved=True) |
LangGraph continues; HiveFlow records decision |
| 10 | Replay | Same intent_id in Tracer/Replay |
Self-hosted audit trail vs LangSmith-only |
Figure 4 — Decision tree (which integration path?)¶
What this figure shows: How to choose Path 1 (native), Path 2 (Sidecar), or LangGraph-only.
flowchart TD
Q1{Already on LangGraph?}
Q1 -->|Yes| Q2{Need Studio HITL / audit?}
Q1 -->|No| Q3{Need visual ops UI?}
Q2 -->|Yes| Sidecar[Path 2: LangGraph Sidecar]
Q2 -->|No| LGOnly[LangGraph only — export optional]
Q3 -->|Yes| Native[Path 1: Native + Studio]
Q3 -->|No| Lib[Path 1: Core/Agent library embed]
Sidecar --> HF[HITL + Blackboard + Studio]
Native --> HF
Decision node guide¶
| Node | Question | If Yes | If No |
|---|---|---|---|
| Q1 | Already standardized on LangGraph? | Go to Q2 — consider Sidecar | Go to Q3 — native HiveFlow is simpler |
| Q2 | Need Studio HITL, audit, or reviewer UI? | Path 2 Sidecar — keep LangGraph execution, add HiveFlow governance | LangGraph only — optional export from HiveFlow for planning |
| Q3 | Need visual ops UI (Orchestrator, Tracer)? | Path 1 Native + Studio — docker compose up |
Path 1 library embed — Core/Agent in your service, no UI |
| Sidecar / Native → HF | Terminal: you get HiveFlow's coordination features | HITL + audited blackboard + self-hosted Studio | — |
| Outcome | Best when | You keep | You gain from HiveFlow |
|---|---|---|---|
| Path 2 Sidecar | LangGraph codebase exists; compliance/HITL needed | LangGraph nodes & checkpointers | Approvals UI, blackboard audit, guards, MCP market |
| Path 1 Native + Studio | Greenfield or full stack acceptable | Single dependency | Everything in one self-hosted product |
| Path 1 library embed | Backend microservice, no UI | Minimal footprint | Scheduler, HITL API, blackboard in-process |
| LangGraph only | No governance requirements | Status quo | Optional TaskGraph export from HiveFlow planning only |
Path 1 — Native HiveFlow (full stack)¶
Use when you want one stack with HITL, blackboard, and Studio without LangGraph.
Quick start¶
docker compose up --build
# Studio: http://localhost:3000
# API: http://localhost:8000
Or library-only:
pip install -e packages/core -e packages/agent
python examples/01_hello_hiveflow.py
python examples/03_hitl_approval.py # HITL
python examples/10_secure_blackboard.py # encrypted blackboard
HiveFlow-only differentiators in code¶
1. HITL gate (no custom interrupt UI)
from hiveflow import HITLManager, HITLAction
gate = await hitl.create_gate(
workflow_id="publish-pipeline",
node_id="compliance_review",
action=HITLAction.APPROVAL,
prompt="Approve before publish?",
context={"draft": draft_text},
timeout_seconds=3600,
)
await hitl.respond(gate.gate_id, approved=True, comment="LGTM")
2. Encrypted, audited blackboard
from hiveflow import HiveFlowConfig, EnvKeyProvider
config = HiveFlowConfig(
blackboard_type="encrypted",
encryption_key_provider=EnvKeyProvider("HIVEFLOW_ENCRYPTION_KEY"),
)
3. MCP-native tools (not LangChain Tool classes)
from hiveflow import MCPPluginManager, PluginMarketplace
marketplace = PluginMarketplace()
manager = MCPPluginManager()
await marketplace.install_plugin("filesystem", manager)
4. Studio Agent mode — NL → plan → canvas → execute
curl -X POST http://localhost:8000/api/agent/plan-only \
-H "Content-Type: application/json" \
-d '{"query": "Research AI agents, write summary, compliance review"}'
With HIVEFLOW_PLAN_HITL=true, reviewers approve the plan in Approvals before Execute DAG.
→ Studio Agent cookbook · Complete Tutorial Part 5
Path 2 — LangGraph Sidecar (recommended for LangGraph teams)¶
Keep LangGraph for execution; add HiveFlow for HITL + audit + Studio.
Step 1 — Plan in HiveFlow¶
Studio: Orchestrator → Agent mode → Plan only
API:
curl -X POST http://localhost:8000/api/agent/plan-only \
-H "Content-Type: application/json" \
-d '{"query": "Research regulation, draft summary, compliance review"}'
Example TaskGraph:
{
"research": {"task": "search", "depends_on": []},
"draft": {"task": "write", "depends_on": ["research"]},
"compliance": {
"task": "review",
"depends_on": ["draft"],
"hitl": {"action": "approval", "prompt": "Approve before publish?"}
},
"final_answer": {"task": "summarize", "depends_on": ["compliance"]}
}
Step 2 — Export to LangGraph spec¶
Python:
from hiveflow.adapters.langgraph import (
taskgraph_to_langgraph,
render_langgraph_python,
dumps_langgraph_spec,
)
spec = taskgraph_to_langgraph(plan, workflow_id="content_pipeline")
print(dumps_langgraph_spec(spec))
# spec["interrupt_before"] includes "compliance" (from hitl config)
python_stub = render_langgraph_python(spec, graph_name="content_graph")
Path("content_graph.py").write_text(python_stub)
Or via execution backend:
from hiveflow.execution import LangGraphExecutionBackend
backend = LangGraphExecutionBackend()
spec = backend.to_langgraph_spec(plan, workflow_id="content_pipeline")
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}'
Toolbar Export LangGraph exports the current Orchestrator canvas without plan-only.
Run the export example:
python examples/16_langgraph_export.py
Step 3 — Implement LangGraph nodes¶
Install LangGraph in your app (not required inside HiveFlow Core):
pip install langgraph langchain-core
Map HiveFlow skill names (search, write, review) to LangGraph node functions. Use exported interrupt_before for human nodes:
# Pseudocode — wire your real tools
graph = builder.compile(
interrupt_before=spec["interrupt_before"],
checkpointer=your_checkpointer,
)
Step 4 — Wire HITL through HiveFlow (Sidecar)¶
When LangGraph pauses at interrupt_before, call HiveFlow instead of building a custom approval Flask app.
Create gate from your interrupt handler:
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="Approve draft before publish?",
context={"draft": draft_text, "intent_id": trace_id},
timeout_seconds=3600,
)
# Notify reviewer — gate.gate_id; poll or webhook
Reviewers use Studio → Approvals, or REST:
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": "LGTM"}'
Resume LangGraph only after approval.
Audit: write agent outputs to SecureBlackboard keyed by intent_id; use Studio Replay / Tracer with the same id.
→ Full walkthrough: LangGraph Sidecar cookbook
Step 5 — Round-trip back to HiveFlow¶
Import LangGraph spec → HiveFlow plan → Studio canvas:
from hiveflow.adapters.langgraph import langgraph_to_taskgraph
plan = langgraph_to_taskgraph(spec)
# POST /api/agent/execute-plan or import to Orchestrator canvas
Path 3 — LangChain Tools without native bridge¶
LangChain Tool wrappers are not auto-imported (planned v0.3). Wrap manually:
Option A — ReActTool (Agent layer)¶
from hiveflow_agent.worker.tools import ReActTool # conceptual pattern
async def my_langchain_tool_fn(**kwargs):
# call your @tool function or StructuredTool
...
tool = ReActTool(
name="my_tool",
description="...",
handler=my_langchain_tool_fn,
parameters={...}, # JSON Schema
)
# Register on ReActWorker
Option B — MCP plugin (preferred in HiveFlow)¶
Expose tools via MCP so any MCP client (including future LangChain MCP adapters) can discover them:
- Implement tool handlers under
packages/agent/worker/tools/or a custom plugin. - Register with
MCPPluginManager. - Install from Studio Capability Market.
HiveFlow standardizes on MCP — the same direction LangChain ecosystem is moving toward.
LLM provider compatibility¶
HiveFlow does not require LangChain LLM classes. Native clients cover the same providers:
| Provider | Package | Env vars |
|---|---|---|
| OpenAI | packages/agent/llm/openai_client.py |
OPENAI_API_KEY, LLM_MODEL |
| Anthropic | packages/agent/llm/anthropic_client.py |
ANTHROPIC_API_KEY |
| Ollama | packages/agent/llm/ollama_client.py |
OLLAMA_BASE_URL |
| DeepSeek | packages/agent/llm/deepseek_client.py |
DEEPSEEK_API_KEY |
Split planning vs execution:
HIVEFLOW_LLM_PLANNING_PROVIDER=openai
HIVEFLOW_LLM_EXECUTION_PROVIDER=anthropic
Echo mode for CI / no API key:
HIVEFLOW_AGENT_ECHO_LLM=true
Core abstraction (hiveflow.llm_client.LLMClient) keeps IntentParser, ReActWorker, and CognitiveOrchestrator backend-agnostic.
→ OpenAI integration · Anthropic integration
Concept mapping reference¶
| LangGraph / LangChain | HiveFlow | HiveFlow advantage |
|---|---|---|
StateGraph |
DAGOrchestrator / CognitiveOrchestrator |
NL plan-only + Studio canvas |
| Graph nodes | Agents + task_handler |
Skill-based scheduler (3 strategies) |
| Shared state | SecureBlackboard |
Encryption + audit keys |
interrupt() |
HITLManager |
Studio Approvals + timeout policies |
| Checkpointer | CheckpointManager |
Time travel + Studio Replay |
| LangChain Tools | MCP + ReActWorker |
Unified marketplace, not class-per-tool |
| LangSmith | Studio Tracer / Analytics | Self-hosted, no per-seat SaaS |
create_react_agent |
HiveMindApp.run_query |
Plan HITL + export to LangGraph |
Execution backends¶
HiveFlow v0.2+ exposes pluggable backends:
from hiveflow.execution import get_execution_backend, LangGraphExecutionBackend
from hiveflow.orchestrator import DynamicOrchestrator
from hiveflow import SecureBlackboard
bb = SecureBlackboard()
native = get_execution_backend("native", orchestrator=DynamicOrchestrator(bb))
result = await native.execute(executable_graph, global_timeout=120.0)
lg = LangGraphExecutionBackend()
spec = lg.to_langgraph_spec(skill_plan)
# await lg.execute(...) → stub until v0.3; use Sidecar today
| Backend | execute() |
Export to LangGraph |
|---|---|---|
native |
✅ production | N/A |
langgraph |
❌ stub (v0.3) | ✅ to_langgraph_spec() |
Decision tree: which path?¶
See Figure 4 in Architecture diagrams & explanations above for the diagram and per-node guide.
Sidecar vs full replacement¶
| Question | Sidecar | Full HiveFlow |
|---|---|---|
| Keep existing LangGraph code? | ✅ | Reimplement nodes as Agents |
| Studio for reviewers? | ✅ | ✅ |
| MCP tool marketplace? | ✅ (coordination layer) | ✅ |
| Lowest migration cost? | ✅ | Medium |
| Single runtime dependency? | ❌ two systems | ✅ |
Limitations (honest, 0.1.x)¶
| Feature | Sidecar today | In-process LangGraph |
|---|---|---|
Topology / depends_on |
✅ export | Planned v0.3 |
HITL → interrupt_before |
✅ | Planned |
| Conditional edges | ❌ | ❌ |
| Checkpoint metadata round-trip | ❌ | ❌ |
| LangChain Tool auto-bridge | ❌ manual wrap | Planned v0.3 |
| CrewAI / AutoGen adapters | ❌ | Community |
Hands-on exercises¶
- Sidecar HITL: Run
docker compose up, plan-only a 3-node graph withhitlon the last node, export LangGraph JSON, verifyinterrupt_before. - Native HITL: Run
examples/03_hitl_approval.pyand compare with LangGraph interrupt docs. - Blackboard audit: Run
examples/10_secure_blackboard.py, then open Studio Blackboard during a live workflow. - Round-trip: Export plan →
langgraph_to_taskgraph(spec)→ import to Orchestrator canvas → execute-plan. - Provider swap: Run Agent mode with
HIVEFLOW_AGENT_ECHO_LLM=true, then switch toOPENAI_API_KEYwithout code changes.
Related documentation¶
| Doc | Topic |
|---|---|
| LangGraph Sidecar cookbook | Step-by-step Sidecar |
| LangGraph integration | Adapter API & limits |
| Migrate from LangGraph | Concept map |
| HITL approval | Gate patterns |
| Tutorial Part 4 — Integrations | Examples 15–16 |
| Regulated HITL case study | Compliance story |
| Roadmap | v0.3 LangChain/LangGraph adapter |
Summary¶
- Compatible: LangGraph (export/Sidecar), OpenAI/Anthropic/Ollama/DeepSeek, MCP tools, same LLM APIs as LangChain.
- Not drop-in: LangChain Tools/Chains, CrewAI, AutoGen — wrap or wait for v0.3 bridge.
- HiveFlow's value: HITL, encrypted audited blackboard, guards, self-hosted Studio, MCP-first tools, one TaskGraph from NL to LangGraph export.
Use Sidecar if you already have LangGraph. Use native HiveFlow if you want coordination + UI in one self-hosted stack.