ReActFlow-Agent

Autonomous Multi-Agent AI Travel Intelligence Platform

ReActFlow-Agent is a production-grade, autonomous multi-agent system that researches, plans, and generates comprehensive, personalized travel itineraries — powered by LangGraph, Groq LLMs, RAG memory, and real-time web intelligence.

🚀 Quick Start · 🏗️ Architecture · 🤖 Agents · 🛠️ Tools · 💡 Features · ⚙️ Configuration

---

💡 Features

🧠 Multi-Agent Orchestration 7 specialized AI agents operating in sequence and parallel LangGraph StateGraph with typed state and list reducers Parallel research workers via Send() map-reduce Supervisor feedback loop with autonomous retry logic	🌐 Real-Time Web Intelligence Tavily Search — AI-optimized semantic web search SerpAPI Google Search — organic results and snippets Geolocation intelligence via Maps tool Weather & budget context tools
💾 Persistent RAG Memory ChromaDB vector store — semantic similarity retrieval HuggingFace embeddings — all-MiniLM-L6-v2 Traveler profile persistence — JSON-based user model Cross-session memory — personalization across queries	✨ Premium Gradio Dashboard Live execution pipeline visualizer with animations Streaming agent output — real-time node-by-node updates Rich prose travel reports with Merriweather typography Editable traveler profile with instant persistence

---

🏗️ Architecture

Graph Execution Flow

User Query
    │
    ▼
┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│ 🧠 Planner  |────▶│ 💾 Memory    │────▶│ 👤 Profile   │
│ Agent       │      │ Agent (RAG)  │      │ Agent        │
└─────────────┘      └──────────────┘      └──────────────┘
                                                │
                              ┌─────────────────┤
                              │     Parallel Send()
                    ┌─────────▼──────────────────────────┐
                    │  🌐 Research Worker  ×  3 tasks    |
                    │  [Tavily + SerpAPI + Maps]         │
                    └─────────────────────┬──────────────┘
                                          │ Merge + Reduce
                                          ▼
                              ┌───────────────────────┐
                              │ 🧭 Supervisor Agent   │
                              │ approve / retry loop  │
                              └───────────┬───────────┘
                                          │ approve
                          ┌───────────────▼───────────────┐
                          │       📅 Itinerary Agent      │
                          └───────────────┬───────────────┘
                                          │
                          ┌───────────────▼───────────────┐
                          │       📝 Summarizer Agent     │
                          │  (saves to RAG memory)        │
                          └───────────────┬───────────────┘
                                          │
                                          ▼
                              ✅  Final Travel Report

Key Design Patterns

Pattern	Implementation
Map-Reduce	Send() dispatches N parallel research tasks; operator.add reducer merges results
State Typing	Annotated[list, operator.add] on research_results, sources, agent_logs
Supervisor Loop	Conditional routing with retry cap (max 2), decision moved into node not router
RAG Pipeline	ChromaDB + HuggingFace embeddings for cross-session travel memory retrieval
Profile Extraction	Groq structured output → Pydantic UserProfile → persisted JSON

---

🖥️ Interface Gallery

Here is a walk-through of the ReActFlow-Agent dashboard and execution workflow:

👤 Traveler Profile Configuration

Set your travel style, preferred transportation, food preferences, and climate style. The profile is automatically persisted locally as a JSON model and retrieved to guide all subsequent agent routing and recommendations.

🔍 Live Multi-Agent Research Execution

See the parallel agent execution live. As the planner node breaks down your query into independent tasks, parallel Groq research workers spin up, call Tavily/SerpAPI, and output live execution logs.

💾 Semantic RAG Memory Retrieval

Before planning, the system performs a semantic similarity search in ChromaDB. Relevant historical preferences and past itineraries are injected as custom context to provide context-aware planning across sessions.

📅 Rich Day-by-Day Itinerary

The agent designs structured daily modules for Morning, Afternoon, Evening, Food, Transport, and Budget details.

📄 Final Consolidated Travel Report

The end product is a beautifully synthesized markdown document containing local weather advice, attraction logs, budgeting projections, packing lists, itineraries, and citations.

---

🤖 Agents

🧠 Planner Agent

Model: llama-3.1-8b-instant

Decomposes the user's raw travel query into 3 focused research sub-tasks (capped to prevent TPM saturation). Uses structured output to return a TravelPlan with a tasks: list[str] field.

Input:  { "user_query": "Plan a 7-day budget trip to Japan..." }
Output: TravelPlan(tasks=["Japan budget accommodation", "Tokyo transport", "Food guide"])

---

💾 Memory Agent

Store: ChromaDB + sentence-transformers/all-MiniLM-L6-v2

Performs semantic similarity search against all previous travel sessions and returns relevant context to personalize the current run.

# Retrieval
memories = retrieve_memory(user_query)  # → List[Document]

# Storage (after summarizer)
save_memory(f"User Query:\n{query}\n\nFinal Response:\n{response}")

---

👤 Profile Agent

Model: llama-3.1-8b-instant

Extracts traveler preferences from the query and merges them into the persistent profile. Fields are deduplicated on lists and overwritten on scalars.

class UserProfile(BaseModel):
    budget_style:          str       # "budget" | "mid-range" | "luxury"
    preferred_transport:   str       # "train" | "flight" | "car"
    climate_preference:    str       # "cold" | "hot" | "temperate"
    travel_style:          str       # "adventure" | "backpacker" | "luxury"
    favorite_destinations: list[str] # ["Japan", "Italy"]
    food_preferences:      list[str] # ["local", "sushi"]

---

🌐 Research Workers (Parallel)

Model: llama-3.3-70b-versatile

Each worker independently searches Tavily + SerpAPI and synthesizes results into a ResearchResult with findings: list[str] and sources: list[Source]. Results are automatically merged via the operator.add LangGraph reducer — no manual aggregation needed.

Why 70B here? Smaller models (8B) fail to reliably call nested structured output schemas (ResearchResult containing List[Source]). The 70B model is essential for reliable tool-call generation.

---

🧭 Supervisor Agent

Model: llama-3.1-8b-instant

Quality-gates the research. Outputs approve or retry. Retry routes back to the Profile node for context re-enrichment. Hard cap at 2 retries prevents infinite loops.

class SupervisorDecision(BaseModel):
    decision: str   # "approve" | "retry"
    feedback: str   # Explanation for retry, or approval note

---

📅 Itinerary Agent

Model: llama-3.3-70b-versatile

Generates a detailed day-by-day markdown itinerary from the merged research findings. Each day includes Morning / Afternoon / Evening / Food / Transport / Budget sections.

---

📝 Summarizer Agent

Model: llama-3.3-70b-versatile

Synthesizes research findings, memories, itinerary, and sources into the final comprehensive travel report with all sections: Overview, Weather, Attractions, Food, Budget, Transport, Tips, Itinerary, and Sources. Saves the response to RAG memory for future sessions.

---

🛠️ Tools

Tool	Description	API
tavily_search	AI-optimized semantic web search, returns clean structured results	Tavily
serp_search	Google organic search results + snippets via SerpAPI	SerpAPI
maps_tool	Geolocation, distance, and place data	Geopy
weather_tool	Weather context for destination planning	—
budget_tool	Budget estimation context	—
clothing_tool	Climate-based clothing recommendations	—

---

📁 Project Structure

ReActFlow-Agent/
│
├── app.py                    # Gradio dashboard + streaming runner
│
├── graph/
│   └── workflow.py           # LangGraph StateGraph definition
│
├── agents/
│   ├── planner_agent.py      # Task decomposition
│   ├── profile_agent.py      # Preference extraction
│   ├── research_agent.py     # Web research + synthesis
│   ├── supervisor_agent.py   # Quality control + routing
│   ├── itinerary_agent.py    # Day-by-day schedule generation
│   ├── summarizer_agent.py   # Final report synthesis
│   └── react_agent.py        # ReAct reasoning agent (base)
│
├── memory/
│   ├── rag_memory.py         # Save + retrieve from ChromaDB
│   ├── vector_store.py       # ChromaDB client initialization
│   ├── profile_memory.py     # JSON profile load/save
│   └── user_profile.json     # Persisted traveler profile
│
├── schemas/
│   ├── research_schema.py    # ResearchResult + Source models
│   ├── user_profile.py       # UserProfile Pydantic model
│   └── state.py              # Shared state types
│
├── tools/
│   ├── tavily_search.py      # Tavily web search tool
│   ├── serp_search.py        # SerpAPI Google search tool
│   ├── maps_tool.py          # Geolocation tool
│   ├── browser_tool.py       # Web scraping (deprecated)
│   ├── weather_tool.py       # Weather context tool
│   ├── budget_tool.py        # Budget estimation tool
│   └── clothing_tool.py      # Clothing recommendations
│
├── config/
│   └── langsmith_config.py   # LangSmith tracing setup
│
├── prompts/
│   └── prompts.py            # Shared prompt templates
│
├── images/                   # README assets
├── .env                      # API keys (see below)
├── .env.example              # Template
└── requirements.txt

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/Dakshin10/ReActFlow-Agent.git
cd ReActFlow-Agent

2. Create Virtual Environment

python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure API Keys

Copy the example environment file and fill in your keys:

cp .env.example .env

# .env
GROQ_API_KEY=gsk_...           # https://console.groq.com
TAVILY_API_KEY=tvly-...        # https://tavily.com
SERPAPI_API_KEY=...            # https://serpapi.com
LANGCHAIN_API_KEY=lsv2_...     # https://smith.langchain.com (optional tracing)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=ReActFlow-Agent

5. Launch the App

python app.py

Open http://127.0.0.1:7860 in your browser.

---

⚙️ Configuration

Model Strategy

Agent	Model	Reason
Planner	llama-3.1-8b-instant	Simple list output, fast
Profile	llama-3.1-8b-instant	Flat Pydantic schema, fast
Research	llama-3.3-70b-versatile	Nested structured output reliability
Supervisor	llama-3.1-8b-instant	Binary decision, fast
Itinerary	llama-3.3-70b-versatile	Long-form quality markdown
Summarizer	llama-3.3-70b-versatile	Comprehensive report quality

All agents have max_retries=6 for automatic Groq rate-limit backoff.

Tuning Parallelism

The planner is capped at 3 parallel research tasks by default to stay within Groq's free-tier TPM limits. Upgrade your Groq plan to increase this:

# graph/workflow.py — planner_node
tasks = result.tasks[:3]  # ← increase for paid tiers

---

🧩 LangGraph State Design

class GraphState(TypedDict):
    user_query:         str
    tasks:              list
    # operator.add reducer — safe parallel merge
    research_results:   Annotated[list, operator.add]
    sources:            Annotated[list, operator.add]
    agent_logs:         Annotated[list, operator.add]
    retrieved_memories: list
    supervisor_feedback:str
    retry_count:        int
    decision:           str
    itinerary:          str
    user_profile:       dict
    final_response:     str

Critical: Annotated[list, operator.add] is required on any key that receives writes from parallel Send() branches. Without it, LangGraph will deadlock or silently overwrite results.

---

🐛 Known Issues & Fixes Applied

Issue	Root Cause	Fix
Graph freezes after research	Missing operator.add reducer on research_results	Added Annotated[list, operator.add] to all parallel keys
UserProfile 400 BadRequest	Groq returning list[str] fields as plain str	Added Field(description="MUST be an array...") to schema
Router state mutation	state["retry_count"] += 1 inside a read-only router	Moved to supervisor_node return dict
413 Request Too Large	Browser scraping 15,000+ chars into LLM context	Eliminated scraping; condensed to title+url+snippet only
429 TPM Rate Limit	17 parallel workers hitting Groq simultaneously	Capped planner at 3 tasks
Model decommissioned	llama3-8b-8192 removed from Groq	Migrated to llama-3.1-8b-instant
Nested schema tool-call failure	8B model can't call ResearchResult + List[Source] reliably	Research agent uses 70B model exclusively

---

🗺️ Example Queries

Plan a 10-day budget winter trip to Japan for a solo college student who loves food and hiking

7-day luxury honeymoon in Maldives with underwater dining and spa experiences

3-day weekend budget city break in Amsterdam for two people who love museums and cycling

2-week backpacking route through Southeast Asia (Thailand, Vietnam, Cambodia) under $1500

---

📦 Requirements

gradio
langchain
langgraph
langchain-core
langchain-community
langchain-groq
langchain-tavily
langsmith
tavily-python
python-dotenv
google-search-results
beautifulsoup4
requests
chromadb
langchain-chroma
sentence-transformers
langchain-huggingface
geopy
pydantic

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ❤️ using LangGraph · Groq · Gradio · ChromaDB

If you find this project useful, please consider giving it a ⭐