🧠 Supervisor-Agent-System

A production-ready, hierarchical Multi-Agent system built with LangGraph and Google Gemini.

This project demonstrates an advanced Hub-and-Spoke (Supervisor-Worker) AI architecture. Instead of agents sharing a single messy context, a central Supervisor dynamically routes tasks to specialized, independent worker agents (a Researcher and a Python Coder). Each worker operates within its own execution loop and reports only the final results back to the Supervisor.

🚀 Key Architectural Features & Skills Demonstrated

• Hierarchical Routing (StateGraph): Implemented a deterministic router using structured outputs (with_structured_output) to manage workflow delegation efficiently.
• Production-Ready Guardrails: Engineered robust recursion limits (recursion_limit: 15) and GraphRecursionError handling to prevent infinite loops during code generation or data retrieval.
• State Persistence (Memory): Integrated LangGraph's MemorySaver to track conversational threads, enabling state recovery and debugging.
• Human-in-the-Loop (HITL) Fallback: Designed a graceful failure mechanism that intercepts iteration limits and prompts the user to inspect the team's internal scratchpad and errors.
• Safe Output Extraction: Developed custom data-sanitization nodes to prevent LLM structural crashes (e.g., handling Gemini's list output anomalies and Model Turn errors).
• ReAct Agent Methodology: Upgraded workers from simple LLM tool-binders to fully autonomous create_react_agent nodes capable of independent reasoning and tool execution.

🛠️ Tech Stack

• Core Framework: LangGraph, LangChain
• LLM Engine: Google Gemini API (gemini-3.8-flash)
• Agent Tools:
  • TavilySearch (Real-time data scraping & research)
  • PythonREPL (Isolated environment for dynamic code execution)
• State Management: TypedDict, MemorySaver (Checkpointers)

🗺️ System Topology

                     [ USER INPUT ]
                           │
                           ▼
               ┌───────────────────────┐
               │   Supervisor Agent    │◄──────────────┐
               │ (Decision & Routing)  │               │
               └───────────┬───────────┘               │
                           │                           │
         ┌─────────────────┼─────────────────┐         │ (Workers report 
         ▼                 ▼                 ▼         │  final results back)
  [ Researcher ]      [ Python Coder ]   [ FINISH ]    │
 (Tavily Search)       (Python REPL)         │         │
         │                 │                 │         │
         └─────────────────┴─────────────────┼─────────┘
                                             ▼
                                          [ END ]