🤖
NEXUS SWARM v1.2 LangGraph
Enterprise Reference Architecture • Cyclical StateGraph + Self-Correction Loops + LangSmith Tracing

Autonomous Multi-Agent Intelligence Swarm

A production-grade, stateful research and strategic intelligence system built with LangGraph, LangChain Core, LangSmith Observability, and Human-in-the-Loop governance.

Test Swarm in Browser View GitHub Repo Terminal Quickstart
Python 3.11 | 3.12 | 3.13 LangGraph v1.2+ LangSmith Tracing BaseStore Long-Term Memory Time-Travel Rewind 45/45 Tests Passing ✓
Live Interactive Demo

Browser Swarm Simulator

Test the multi-agent StateGraph execution, reflection cycle, and executive synthesis directly.

Engine: Client-Side StateGraph Simulator
Human-in-the-Loop Gate
Self-Correction Reflection Loop Max 2 Cycles
🧭
Supervisor
🔬
Researcher
📈
Analyst
⚖️
Critic
🛡️
Human Gate
✍️
Writer
swarm-stream.log
READY
// Press "Launch Swarm Orchestration" to start simulated agent state graph.
Critic Quality Score
-- / 100
Sources Triangulated
--
Latency Overhead
-- ms
Architectural Blueprint

Stateful Multi-Agent Topology

Nexus abandons single-turn prompt chaining in favor of an explicit, cyclic LangGraph StateGraph that supports dynamic task routing, reflection self-correction, and state checkpoints.

🧭

Supervisor Agent

Dynamic orchestrator that analyzes the user's objective, formulates a 4-stage execution plan, tracks step progression, and dynamically routes between specialized agents.

State: plan, current_step, next_agent
🔬

Researcher Agent

Collects empirical data, whitepapers, and live web snippets using search_web. Gathers primary citations and addresses specific critic feedback during revision cycles.

Tools: search_web (DDGS / API)
📈

Data Analyst Agent

Extracts quantitative indicators, percentage changes, financial amounts, and performance benchmarks using extract_metrics to generate verifiable scorecards.

Tools: extract_metrics (Regex & NLP)
⚖️

Critic / Fact-Checker

The reflection engine. Triangulates assertions against collected sources, verifies claims, and computes a 0-100 quality score. Triggers automatic revision cycles if the score is under 80.

Pattern: Reflection & Self-Correction
🛡️

Human-in-the-Loop Gate

Provides an auditable checkpoint via LangGraph's interrupt_before. Allows operators to inspect state, edit prompts, and sign off before final distribution.

Persistence: MemorySaver & SqliteSaver
✍️

Executive Writer Agent

Synthesizes the entire state history into an authoritative executive decision briefing, incorporating an executive summary, KPI scorecard table, and cited sources.

Output: C-Level Markdown Report
Next-Gen LangGraph Features

Time-Travel Replay & Long-Term Memory

Nexus harnesses cutting-edge LangGraph v1.2 capabilities that traditional prompt architectures cannot match: immutable checkpoint rewinding and cross-thread semantic memory stores.

Time-Travel & State History

app.get_state_history(config)

Every node transition is persisted as an immutable checkpoint in SQLite. Operators can inspect the exact historical state at step 2 or step 4, modify input parameters, and fork execution along a new branch without re-running earlier expensive stages.

# Inspect checkpoint timeline via CLI
uv run python -m langgraph_multi_agent_system.cli --time-travel <THREAD_ID>

Cross-Thread Long-Term Memory

langgraph.store.base.BaseStore

Checkpointers manage state within a single thread, but LangGraph's BaseStore provides cross-session recall. Past research discoveries, domain benchmarks, and operator preferences are recalled across completely different threads.

# Search shared memory store via CLI
uv run python -m langgraph_multi_agent_system.cli --memory-search "LangGraph"
📓

Interactive Jupyter Masterclass Notebook

Step-by-step code tutorial: state manipulation, checkpoint rewinding, and live LangSmith trace querying.

Open Masterclass Notebook
Enterprise Observability

End-to-End Tracing via LangSmith

Multi-agent systems cannot be run blindly. Nexus is natively instrumented for LangSmith. Every node invocation, prompt input, token spend, latency delta, and reflection score is recorded in an auditable distributed trace tree.

Sub-Millisecond Span Capture: Track latency bottlenecks across agent handoffs and tool executions.
Granular FinOps Token Accounting: Inspect exact token usage per agent node to prevent cost runaways.
Automated Regression Benchmarks: Custom evaluators continuously score topic coverage and critic rigor.
Trace: nexus-multi-agent-system STATUS: 200 OK
▼ nexus-swarm (root) [1.42s • 2,140 tokens • $0.0031]
├─► supervisor [120ms • 410 tokens]
├─► researcher [415ms • search_web: 4 results]
├─► analyst [92ms • extract_metrics: 3 KPIs]
├─► critic [180ms • score: 96/100, verified: true]
├─► human_gate [0ms • operator approved]
└─► writer [610ms • 1,180 tokens]
Project: nexus-multi-agent-system Model: GPT-4o-mini / Hybrid
LangSmith Native Platform Integrations

Distributed Tracing

Hierarchical trace trees capturing all subagent handoffs, DuckDuckGo searches, metric parsing, and token spend.

Datasets & Experiments

Continuous benchmarking on nexus-benchmark-dataset with automated multi-run regression comparison.

Automated Evaluators

Scorers for topic completeness, critic self-correction rigor, and quantitative data density logged per run.

Annotation Queues

nexus-human-review-queue routes runs requiring Human-in-the-Loop sign-off for operator feedback.

Prompts Hub

System prompt templates for all 5 agents synced and version-controlled directly in LangSmith Prompt Hub.

LangGraph Studio

Native langgraph.json specification allowing visual step-through, node editing, and state inspection.

Empirical Research & Benchmarks

Single-Agent vs Multi-Agent Swarms

Objective benchmark results comparing 5 architectural baselines evaluated on identical enterprise research objectives.

Mode A (Deterministic Simulation): Measures LangGraph StateGraph engine overhead (< 30 ms). Live LLM execution takes ~3.5s dominated by model API roundtrips.
Architecture Baseline Sources Extracted KPIs Extracted Factual Grounding (Objective) Avg Tokens Observed Trade-off
Baseline A: Single-Agent Direct 0.0 0.0 0.0% ~31 Zero citations; high hallucination risk.
Baseline B: Single-Agent + Tools 2.0 3.3 32.7% ~222 Basic search grounding; single-pass without self-correction.
Baseline C: Sequential Multi-Agent 2.0 3.3 72.0% ~609 Role separation, but errors in research cascade to writer.
Baseline D: Parallel Map-Reduce 6.0 7.3 85.0% ~1,475 3x higher source density across decomposed angles; lacks self-correction.
Baseline F: Nexus Swarm (Reflection) 6.0 7.3 100.0% ~2,694 100% verified citations & quantitative KPIs; requires ~3.5x tokens of sequential.
Developer Setup

Get Started in Under 60 Seconds

Powered by modern uv package manager for instantaneous builds.

1 Clone Repository & Sync Dependencies
git clone https://github.com/phlppgdfry/langgraph-multi-agent-system.git
cd langgraph-multi-agent-system
uv sync
2 Configure LangSmith Credentials
uv run python -m langgraph_multi_agent_system.cli --configure
3 Run Terminal Swarm or Launch Web Dashboard
# Run Rich Interactive CLI
uv run python -m langgraph_multi_agent_system.cli "Analyze Enterprise Agentic FinOps"

# Or Launch Streamlit Web UI
uv run streamlit run src/langgraph_multi_agent_system/app.py