Part 2 — Workflows¶
Build multi-agent pipelines, add human approval, recover from failures, stream events, and connect RAG + MCP tools.
2.1 Multi-agent collaboration (Example 02)¶
Pattern: research → write → review via the blackboard.
python examples/02_multi_agent.py
Each agent:
- Reads upstream keys from the blackboard (
view.get()). - Processes the ECM payload.
- Writes downstream keys (
view.put()).
Scheduling order is explicit — you schedule ECM messages in sequence (or use a DAG orchestrator for automatic dependencies).
# After research completes, schedule writer
await hf.scheduler.schedule(ECM(
trace_id="pipeline-1",
intent="Write article",
intent_id="write-1",
emitter="scheduler",
required_skills=["write"],
payload={"topic": "AI Trends 2025"},
))
Design tip: Keep blackboard keys stable and versioned (article_draft_v2) when HITL may edit intermediate results.
Deep dive: Multi-agent debate cookbook.
2.2 Human-in-the-Loop (Example 03)¶
Pause before irreversible actions (publish, send email, deploy).
python examples/03_hitl_approval.py
Core API:
from hiveflow import HITLManager, HITLAction
hitl = HITLManager()
gate = await hitl.create_gate(
workflow_id="content-pipeline",
node_id="publish_review",
action=HITLAction.APPROVAL,
prompt="Approve publishing this draft?",
context={"title": draft["title"], "body": draft["body"]},
)
# Workflow waits until:
await hitl.respond(gate.gate_id, approved=True, comment="LGTM")
In Studio, open Approvals to approve/reject gates. With HIVEFLOW_PLAN_HITL=true, plans are gated at node_id=plan_approval before execution.
Deep dive: HITL approval cookbook.
2.3 Checkpoints & time travel (Example 04)¶
Save workflow state snapshots and restore to a previous step.
python examples/04_checkpoint.py
Use cases:
- Retry failed steps without re-running expensive upstream work.
- Audit trail for regulated industries.
- Studio Replay page for post-mortems.
Deep dive: Checkpoint recovery cookbook.
2.4 Streaming events (Example 05)¶
Emit typed SSE events for tokens, tool calls, and node lifecycle.
python examples/05_streaming.py
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)
Wire StreamBuffer to FastAPI StreamingResponse for browser clients. Studio Tracer consumes WebSocket events with unified intent_id / trace_id.
2.5 RAG pipeline (Example 06)¶
Index documents, retrieve chunks, optionally generate answers.
python examples/06_rag_pipeline.py
Typical flow:
- Create a knowledge base.
- Index documents (title + body).
- Query with natural language.
- Retrieve ranked sources; plug in
llm_clientfor generation.
Deep dive: RAG + MCP cookbook.
2.6 MCP tools (Example 07)¶
Unified tool discovery and invocation via Model Context Protocol.
python examples/07_mcp_tools.py
Register tools, invoke by name, swap providers without changing agent code. Studio Capability Market surfaces installed MCP plugins.
2.7 Workflow patterns summary¶
| Pattern | When to use | Example |
|---|---|---|
| Sequential pipeline | Fixed steps, clear handoffs | 02_multi_agent.py |
| HITL gate | Human approval before side effects | 03_hitl_approval.py |
| Checkpoint | Fault tolerance, audit | 04_checkpoint.py |
| Streaming | Chat UX, live progress | 05_streaming.py |
| RAG + MCP | Knowledge + external tools | 06, 07 |
2.8 Exercises¶
- Add an HITL gate between writer and reviewer in Example 02.
- Stream token events from a mock LLM handler in Example 05.
- Index a local markdown file in Example 06 and query it.
Next¶
→ Part 3 — Advanced: cognitive planning, security, scaling, plugins.