🧠 Agent Mind Map Visualizer

Watch your AI agent think in real-time.

A plug-and-play visualization tool that transforms LangChain agent execution into an animated mind map. Built for the new create_agent API (LangChain v1.0+). Perfect for demos, debugging, presentations, and social media content.

---

🎬 What It Does

When you run a LangChain agent through this visualizer, you see:

• 🧠 Thought nodes bloom when the LLM starts reasoning
• 🔧 Tool nodes appear when tools are invoked
• ✅ Result nodes show tool outputs
• 🎉 Final answer displays prominently when complete
• Animated connections draw between related steps
• Real-time updates via WebSocket streaming

Instead of staring at terminal logs, you get a beautiful, animated graph that shows exactly how your agent thinks — perfect for LinkedIn/Twitter demos, client presentations, or understanding complex agent behavior.

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 18+
• An OpenAI API key (or Anthropic key)

Installation

# Clone or unzip the project
cd agent-mind-map-visualizer

# Copy environment template
cp .env.example .env

# Add your API key to .env
echo "OPENAI_API_KEY=sk-your-key-here" >> .env

Running

Option 1: Using the start script (Recommended)

chmod +x start.sh
./start.sh

This automatically:

• Creates a Python virtual environment
• Installs all dependencies
• Starts both backend and frontend servers

Option 2: Manual startup

# Terminal 1: Backend
cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python main.py

# Terminal 2: Frontend
cd frontend
npm install
npm run dev

Open the App

Navigate to http://localhost:5173 and start chatting!

---

📁 Project Structure

agent-mind-map-visualizer/
│
├── config.yaml                 # 👈 Configure your agent here
├── .env                        # API keys (create from .env.example)
├── start.sh                    # One-command startup script
│
├── backend/
│   ├── main.py                 # FastAPI WebSocket server (uses stream_mode="updates")
│   ├── agent_loader.py         # Dynamic agent loading
│   └── requirements.txt        # Python dependencies
│
├── frontend/
│   ├── src/
│   │   ├── App.tsx             # Main application
│   │   ├── components/
│   │   │   ├── MindMap.tsx     # Graph visualization
│   │   │   ├── Node.tsx        # Animated node component
│   │   │   └── InputPanel.tsx  # Chat input UI
│   │   ├── hooks/
│   │   │   └── useAgentSocket.ts  # WebSocket connection
│   │   └── types.ts            # TypeScript definitions
│   ├── package.json
│   └── vite.config.ts
│
├── agents/                     # 👈 Drop your agents here
│   └── rag_agent/              # Example agent included
│       ├── __init__.py
│       └── agent.py            # Uses new create_agent API
│
└── docs/
    └── BRING_YOUR_OWN_AGENT.md # Detailed integration guide

---

🔌 Using Your Own Agent

The visualizer works with any LangChain agent built using the new create_agent API.

Step 1: Add Your Agent

Copy your agent folder into the agents/ directory:

agents/
├── rag_agent/          # Example agent
└── my_custom_agent/    # 👈 Your agent here
    ├── __init__.py
    └── agent.py

Step 2: Create Your Agent with create_agent

Your agent should use LangChain's new create_agent function:

# agents/my_custom_agent/agent.py

from langchain.agents import create_agent
from langchain.tools import tool


@tool
def my_tool(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"


def create_my_agent(model: str = "openai:gpt-4o-mini"):
    """
    Factory function that creates the agent.
    
    Args:
        model: Model identifier (e.g., "openai:gpt-4o", "anthropic:claude-sonnet-4-6")
    
    Returns:
        A compiled LangGraph agent
    """
    return create_agent(
        model=model,
        tools=[my_tool],
        system_prompt="You are a helpful assistant.",
        name="my_agent",
    )

Step 3: Update Config

Edit config.yaml:

agent:
  module_path: "agents/my_custom_agent"
  entry_point: "create_my_agent"

Step 4: Run

./start.sh

That's it! The visualizer will now use your agent.

---

⚙️ Configuration

config.yaml

# Agent Configuration (New create_agent API)
agent:
  module_path: "agents/rag_agent"     # Path to agent (relative or absolute)
  entry_point: "create_rag_agent"     # Function that returns the agent
  env_vars:                           # Optional: inject environment variables
    # OPENAI_API_KEY: "sk-..."

# Server Settings
server:
  host: "0.0.0.0"
  port: 8000
  cors_origins:
    - "http://localhost:5173"
    - "http://localhost:3000"

# Visualization Theme
visualization:
  nodes:
    thought_color: "#8B5CF6"    # Purple - LLM reasoning
    tool_color: "#F59E0B"       # Amber - Tool calls
    result_color: "#10B981"     # Green - Results
    error_color: "#EF4444"      # Red - Errors
    input_color: "#3B82F6"      # Blue - User input
    output_color: "#EC4899"     # Pink - Final output
  
  animation:
    node_appear: 300            # ms
    connection_draw: 200        # ms
    pulse_interval: 1500        # ms

# Logging
logging:
  level: "INFO"                 # DEBUG, INFO, WARNING, ERROR

Environment Variables (.env)

# Required: At least one LLM API key
OPENAI_API_KEY=sk-your-openai-key

# Optional: For Anthropic-based agents
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Optional: LangSmith tracing
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langsmith-key
LANGCHAIN_PROJECT=agent-mind-map

Model Identifiers

The new create_agent uses string identifiers in the format provider:model:

# OpenAI models
create_agent(model="openai:gpt-4o", ...)
create_agent(model="openai:gpt-4o-mini", ...)

# Anthropic models
create_agent(model="anthropic:claude-sonnet-4-6", ...)
create_agent(model="anthropic:claude-opus-4-5", ...)

# Auto-inference (provider detected from model name)
create_agent(model="gpt-4o", ...)  # Infers openai:

---

🎨 Node Types & Colors

Node Type	Color	Icon	When It Appears
Input	Blue	📝	User sends a message
Thought	Purple	🧠	LLM starts processing
Tool	Amber	🔧	Tool is invoked
Result	Green	✅	Tool returns result
Action	Cyan	🎯	Agent decides on action
Output	Pink	🎉	Final answer ready
Error	Red	❌	Something went wrong

---

🔄 How It Works

┌─────────────┐     WebSocket      ┌─────────────┐
│   Frontend  │◄──────────────────►│   Backend   │
│  (React)    │    Real-time       │  (FastAPI)  │
└─────────────┘    Events          └──────┬──────┘
                                          │
                                   ┌──────▼──────┐
                                   │   Stream    │
                                   │  Processor  │
                                   └──────┬──────┘
                                          │ stream_mode="updates"
                                   ┌──────▼──────┐
                                   │ LangChain   │
                                   │ create_agent│
                                   └─────────────┘

New Streaming Architecture (LangChain v1.0+)

1. User sends message → Frontend sends via WebSocket
2. Backend receives → Creates agent, calls agent.stream() with stream_mode="updates"
3. Agent executes → LangGraph emits updates after each step (model, tools)
4. Events stream → Backend processes chunks and sends to frontend
5. Frontend renders → Nodes animate into the mind map
6. Agent completes → Final answer displays prominently

Streaming Code Pattern

# No callbacks needed! Uses built-in streaming
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": query}]},
    stream_mode="updates",
    version="v2",
):
    if chunk["type"] == "updates":
        for step_name, step_data in chunk["data"].items():
            # step_name: "model" or "tools"
            messages = step_data["messages"]
            # Process and send to WebSocket...

---

📱 Features

Real-Time Streaming

Every step of agent execution appears instantly — no waiting for completion. Uses LangChain's native stream_mode="updates".

Pan & Zoom

• Drag the canvas to pan
• Scroll to zoom in/out
• Reset button returns to default view

Connection Status

Visual indicator shows WebSocket connection state with auto-reconnect.

Example Queries

Clickable example prompts to quickly test the agent.

Final Answer Card

The agent's response displays in a highlighted card below the graph.

---

🎥 Recording Demos for Social Media

Tips for creating social media content:

1. Use a clean query that demonstrates multiple tool calls
2. Record in 1080p or higher for clarity
3. Slow down — the animations are the star
4. Add captions explaining what's happening
5. Keep it under 60 seconds for Twitter/X
6. Dark theme looks great on social feeds

Recommended screen recording tools:

• macOS: Built-in (Cmd+Shift+5) or OBS
• Windows: OBS or ShareX
• Linux: OBS or SimpleScreenRecorder

---

🛠️ Troubleshooting

"Agent not loaded" error

1. Check your config.yaml paths are correct
2. Verify the entry point function exists and returns a create_agent result
3. Run the loader test:

   cd backend
   python agent_loader.py

WebSocket won't connect

1. Ensure backend is running on port 8000
2. Check CORS origins in config.yaml include your frontend URL
3. Look for errors in the backend terminal

Nodes not appearing

1. Ensure your agent is created with create_agent() (not old AgentExecutor)
2. Check backend logs for streaming events
3. Verify your tools are decorated with @tool

Import errors in your agent

1. Use relative imports: from .tools import my_tool
2. Ensure __init__.py exists in your agent folder
3. Check all dependencies are in requirements.txt

---

🔧 API Endpoints

WebSocket: /ws/agent

Real-time agent interaction.

Send:

{
  "message": "What is the vacation policy?",
  "session_id": "optional-session-id"
}

Receive (stream of events):

{
  "type": "llm_start",
  "timestamp": "2024-01-15T10:30:00Z",
  "run_id": "session-123",
  "data": {
    "node_id": "thought_1",
    "parent_id": "input_0",
    "label": "🧠 Reasoning",
    "preview": "Calling: search_documents"
  }
}

REST: GET /health

Health check endpoint.

REST: GET /config

Returns visualization configuration.

REST: POST /api/query

Non-streaming query (for simple integrations).

{
  "message": "Hello",
  "session_id": "optional"
}

---

🚢 Deployment

Docker (Coming Soon)

# Dockerfile example structure
FROM python:3.11-slim
WORKDIR /app
COPY backend/ ./backend/
RUN pip install -r backend/requirements.txt
# ...

Environment Variables for Production

# Required
OPENAI_API_KEY=sk-...

# Server config
HOST=0.0.0.0
PORT=8000

# Frontend URL for CORS
CORS_ORIGINS=https://your-app.com

---

🔮 Other Visualization Styles

This project implements the Mind Map style. Other styles that can be built:

Style	Best For	Description
Mind Map ✅	Reasoning chains	Nodes bloom outward showing thought process
Mission Control	Multi-agent systems	NASA-style dashboard with status panels
Pipeline	ETL/RAG workflows	Conveyor belt showing data flow
Code Theater	Code generation	Split-screen with live code + output
Workspace Canvas	Computer-use agents	Virtual desktop with windows

Want another style? Check the docs/ folder or open an issue!

---

📊 Migration from Old API

If you have agents using the old AgentExecutor pattern:

Before (Old API)

from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini", callbacks=callbacks)
agent = create_openai_functions_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, callbacks=callbacks)
result = executor.invoke({"input": query})

After (New API)

from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=tools,
    system_prompt="Your prompt here",
)
# Streaming is built-in, no callbacks needed
for chunk in agent.stream({"messages": [...]}, stream_mode="updates"):
    ...

Key Differences:

• No separate AgentExecutor — create_agent returns a ready-to-use graph
• No callbacks — use stream_mode="updates" for real-time events
• Model as string — "openai:gpt-4o" instead of ChatOpenAI(...)
• Messages format — {"messages": [...]} instead of {"input": "..."}

---

🤝 Contributing

Contributions welcome! Areas of interest:

• Additional visualization styles (Dashboard, Pipeline, etc.)
• LangGraph-specific visualization with state machines
• Docker deployment configuration
• Recording/replay functionality
• Custom theming UI
• Multi-agent visualization
• Mobile-optimized view

---

📄 License

MIT License — use freely for personal and commercial projects.

---

🙏 Acknowledgments

Built with:

• LangChain — Agent framework (v1.0+ with create_agent)
• LangGraph — Agent runtime
• FastAPI — Backend API
• React — Frontend UI
• Framer Motion — Animations
• Tailwind CSS — Styling
• Vite — Build tool

---

📬 Contact

Built for AI Engineers who want their demos to shine. ✨

Questions? Issues? Open an issue or reach out!