Weather Forecast Multi-Agent System (MAS)

A production-style 4-agent weather forecasting system built using LangGraph, designed to collect weather data from multiple APIs, reconcile inconsistencies, generate alerts, and provide LLM-powered analysis and recommendations.

Key Features

• Multi-source weather data acquisition
• Deterministic statistical analysis and consensus building
• LLM-powered reasoning, Q&A, and recommendations
• Structured, explainable outputs
• Modular and extensible agent architecture

Architecture

The system is organized around four cooperating agents coordinated via a LangGraph state machine:

Agent 1 – Data Acquisition

• Collects raw weather data from multiple providers
• Normalizes responses into a common schema
• Handles API failures independently
• Outputs structured WeatherData objects with source-level confidence

Agent 2 – Weather Data Report

• Aggregates values across sources
• Computes temperature, humidity, wind statistics, and variance
• Detects anomalies and severe conditions
• Generates actionable alerts with severity levels
• Outputs detailed insights, analysis summary, and weather report

Agent 3 – Query Enhancement

• Reviews user questions for clarity and specificity
• Detects vague or generic queries related to weather
• Uses LLM to rewrite queries for better analysis
• Maintains original meaning while improving detail
• Updates workflow state with enhanced_query

Agent 4 – LLM Analysis & Q&A

• Processes weather reports with multi-provider LLM
• Generates comprehensive analysis and recommendations
• Answers user questions in structured JSON format
• Suggests follow-up questions and evaluates confidence
• Outputs llm_response and llm_analysis

Shared State Model

All agents operate on a shared immutable AgentState containing:

• location, request_id, user_question
• Agent statuses, raw data, consensus, alerts, analysis, and errors
• Execution timing

Execution Flow

1. User provides location and optional question
2. Orchestrator initializes LangGraph
3. Initial AgentState is created
4. Agent 1 fetches and normalizes data
5. Agent 2 analyzes and builds data report
6. Agent 3 reasons, answers, and evaluates confidence
7. Final response formatted and returned

Output Structure

• Workflow status and execution timing
• Agent completion states
• Weather summary and alerts
• LLM-generated insights and answers
• Raw data preview
• Errors (if any)

Project Structure

agents/ # Data acquisition, report, query enhancer, LLM modules
config/ # Environment-based settings
utils/ # LLM and weather API clients
workflows/ # Orchestrator and workflow definitions
main.py # Entry point
.env # API keys & config
README.md
requirements.txt

Configuration

Weather APIs

• OPENWEATHER_API_KEY
• WEATHERAPI_KEY
• VISUALCROSSING_API_KEY

LLM Providers

• OPENAI_API_KEY
• GROQ_API_KEY
• `GEMINI_API_KEY

At least one LLM provider must be available.

Running the System

python main.py "London" "Should I bring an umbrella?"

Design Principles

• Separation of concerns between agents

• Deterministic analysis before LLM reasoning

• Confidence-aware decision making

• Easy extensibility