Skip to content

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


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:

  1. Implement tool handlers under packages/agent/worker/tools/ or a custom plugin.
  2. Register with MCPPluginManager.
  3. 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

→ Migrate from 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

  1. Sidecar HITL: Run docker compose up, plan-only a 3-node graph with hitl on the last node, export LangGraph JSON, verify interrupt_before.
  2. Native HITL: Run examples/03_hitl_approval.py and compare with LangGraph interrupt docs.
  3. Blackboard audit: Run examples/10_secure_blackboard.py, then open Studio Blackboard during a live workflow.
  4. Round-trip: Export plan → langgraph_to_taskgraph(spec) → import to Orchestrator canvas → execute-plan.
  5. Provider swap: Run Agent mode with HIVEFLOW_AGENT_ECHO_LLM=true, then switch to OPENAI_API_KEY without code changes.

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.