🌌 Multi-Agent AI Workflow Platform

An ultra-premium, production-ready Multi-Agent Orchestration Platform that allows you to define complex tasks, assemble a swarm of specialized AI agents, and watch them collaborate, research, and execute tasks via a beautifully animated visual graph.

---

📖 Table of Contents

1. How It Works
2. Deep Dive into Features
3. The Agent Swarm
4. Architecture Overview
5. Supported Models
6. Getting Started

---

⚙️ How It Works

This platform utilizes LangGraph (built on top of LangChain) to orchestrate a stateful, cyclic workflow between multiple Large Language Models (LLMs). Instead of relying on a single prompt to generate an answer, this platform breaks a task down and routes it through a network of specialized agents.

1. State Management: When a workflow is executed, a global WorkflowState dictionary is initialized. This state tracks the active subtasks, research data, written content, code outputs, and token/cost analytics.
2. Dynamic Routing: Based on the user's initial task, the Planner agent analyzes the requirement and generates an execution order (e.g., ['researcher', 'coder', 'writer', 'reviewer']).
3. Graph Execution: LangGraph compiles this plan into a DAG (Directed Acyclic Graph) or cyclic graph. The engine transitions state from one node (agent) to the next.
4. Tool Execution: If an agent determines it needs external data (e.g., the Researcher needing real-time data), it binds to its configured tools (like DuckDuckGo Search or a Python REPL), executes the tool, and feeds the result back into the global state.
5. Real-time Logging: Every transition, token count, and output is logged asynchronously to a SQLite database, allowing the frontend to reconstruct the exact workflow execution later.

---

🚀 Deep Dive into Features

1. Visual Workflow Orchestration

Gone are the days of staring at a blank terminal waiting for an LLM script to finish. The frontend integrates React Flow to visually map the LangGraph nodes. During execution (and in the Replay section), you can see exactly which agent is currently active, how data flows between them, and the ultimate path taken to reach the final result.

2. State Persistence & The Replay Engine

Every single execution is meticulously logged into the database (ExecutionLogs table).

• Logs Page: View a step-by-step trace of what happened, how long it took, and what errors occurred.
• Replay Page: A dedicated visual interface where you can "rewind" and "fast-forward" through historical workflows. You can click on individual nodes to see exactly what prompt was sent, what the agent outputted, and what tools were invoked at that specific moment in time.

3. Tokenomics & Cost Analytics

Multi-agent systems can get expensive quickly. This platform includes built-in token tracking and cost estimation.

• It tracks prompt_tokens and completion_tokens natively.
• It dynamically calculates costs based on the specific LLM used (e.g., Groq vs Gemini pricing models).
• The Dashboard provides aggregate statistics on total platform cost, while individual execution logs show micro-costs per agent step.

4. Agent Tooling Ecosystem

Agents are not just text generators; they are capable of taking action:

• Web Search: Utilizing duckduckgo_search to bypass hallucinations and fetch real-time data.
• Python REPL: The Coder agent can write Python code, execute it securely within a localized REPL environment, read the terminal output, and self-correct if the code fails.

5. Ultra-Premium UI/UX

The frontend was built with extreme attention to aesthetic detail:

• Glassmorphism: Cards and panels feature backdrop blurs, inset shadows, and glowing borders.
• Micro-Animations: Staggered fade-ins, floating icons, and smooth slide-down accordions make the platform feel alive.
• Rich Rendering: Final results and logs are rendered using react-markdown and remark-gfm, ensuring beautiful typography, structured tables, and styled code blocks.

---

🤖 The Agent Swarm

The platform comes pre-configured with a roster of specialized agents, though you can create your own via the UI.

Agent Role	Goal & Capabilities	Typical Tools
Planner	Decomposes complex tasks into actionable sub-tasks and dictates the orchestration route.	None
Researcher	Crawls the web for up-to-date information, summarizes findings, and cites sources.	web_search
Coder	Writes, executes, and debugs algorithms and data analysis scripts.	python_repl
Writer	Synthesizes research and code outputs into a cohesive, professional markdown report.	None
Reviewer	Critiques the final output for accuracy, tone, and completeness before marking the workflow as complete.	None

---

🏗️ Architecture Overview

Backend (/backend)

• main.py: The FastAPI entry point. Defines the REST API routes for CRUD operations on agents, triggering workflows, and retrieving logs.
• orchestrator.py: The core LangGraph engine. It contains the LLM factory (Groq, Gemini, OpenRouter), tool bindings, state reducer logic, and node definitions.
• models.py: Contains SQLAlchemy ORM models (AgentDB, WorkflowDB, ExecutionLogDB), Pydantic validation schemas, and the WorkflowState TypedDict.

Frontend (/frontend)

• src/pages/: Contains the main views: Dashboard, Agents, Execute, Logs, Replay, Tokens.
• src/store/useStore.js: A Zustand global state manager ensuring your workflow data persists across tab navigation.
• src/components/WorkflowGraph.jsx: A React Flow implementation that parses the backend's graph definition into visual nodes and edges.

---

🧠 Supported Models

The platform allows dynamic model selection per agent. By default:

• Groq (qwen/qwen3-32b): Used for the Planner and Coder. Blazing fast inference speeds make it perfect for logical routing and code generation.
• Gemini (gemini-2.5-flash): Used for the Writer and Reviewer. Excels at long-context creative writing and structured document generation.
• OpenRouter (google/gemma-4-26b-a4b-it:free): Available as a flexible fallback for custom agents.

---

🚀 Getting Started

Prerequisites

• Node.js (v18+)
• Python 3.10+

1. Backend Setup

Open a terminal and navigate to the backend folder:

cd backend

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Create a .env file in the backend/ directory and add your API keys:

GROQ_API_KEY=your_groq_key
GOOGLE_API_KEY=your_gemini_key
OPENROUTER_API_KEY=your_openrouter_key

Run the backend server:

uvicorn main:app --reload --port 8000

2. Frontend Setup

Open a new terminal and navigate to the frontend folder:

cd frontend

# Install dependencies
npm install

# Start the development server
npm run dev

Navigate to http://localhost:3000 in your browser. You're ready to start orchestrating!