ChatAgent: An Intelligent Agentic AI Chatbot System

ChatAgent is a production-ready agentic AI chat system powered by LangGraph. It orchestrates a sophisticated multi-stage pipeline that intelligently processes each user message through safety validation, intent analysis, adaptive planning, tool execution, response generation, and memory management—enabling context-aware, multi-turn conversations with optional automatic summarization for extended dialogs.

---

See it in action

The web UI delivers real-time streaming responses, seamless multi-turn conversation threads, and beautifully formatted answers complete with syntax-highlighted code blocks. Watch as the system analyzes your query, plans its approach, executes tools when needed, and synthesizes intelligent responses—all without losing context across long conversations.

---

Architecture at a glance

ChatAgent implements a sophisticated multi-stage reasoning pipeline built on LangGraph's state-graph architecture. Each user message flows through intelligent conditional routing: safety validation → semantic analysis → dynamic planning (if needed) → parallel tool execution → response synthesis → memory management → optional summarization.

User Input → Input Guard → Analyzer → [Planner ↔ Executor] → Responder → Memory Orchestrator → [Summarizer] → Output

---

Workflow Components

The graph below matches the implementation in src/graph/builder.py. Conditional edges intelligently route messages based on content analysis—ensuring safe messages proceed through the reasoning pipeline while unsafe content is rejected early.

Stage	Purpose	Key Features
Input Guard	Security gateway for each message	Validates message safety; routes to safe path via Analyzer or unsafe path to end; extensible for custom moderation rules
Analyzer	Intent understanding & planning assessment	Produces structured AnalyzerOutput with intent classification, planning requirement flag, and optional decomposed sub-questions
Planner	Dynamic execution planning	Generates execution_plan with LLM tasks and tool-call tasks using registered tool schemas; supports complex multi-step processes
Executor	Parallel task execution engine	Runs LLM sub-tasks and tool calls concurrently via asyncio.gather; stores combined results in execution_result
Responder	Answer generation & synthesis	Routes to direct response or synthesizes final answer from executor results; streams tokens for smooth user experience
Memory Orchestrator	Context-aware memory management	Estimates token usage; triggers summarization when context exceeds SUMMARY_TOKEN_THRESHOLD
History Summarizer	Long-context management	Updates conversation summary and last_summary_msg_id to maintain token efficiency in extended chats

Available Tools (src/tools/):

• Weather API: Real-time weather data integration
• Tavily Search: Web search for current information

Tools are dynamically dispatched based on planner decisions via the registry system in src/tools/registry.py.

Web API (src/api/app.py):

• Framework: FastAPI + Uvicorn
• Features: Server-Sent Events (SSE) for token streaming, multi-turn session support via LangGraph MemorySaver checkpoints, health monitoring endpoints
• Frontend: Jinja2-templated web UI with modern styling and real-time response streaming

---

Tech stack

• Orchestration: LangGraph — State graph orchestration with conditional edge routing, streaming support, and persistent checkpointing
• LLM Integration: LangChain + Groq API — Multi-model support with configurable parameters (temperature, max tokens, reasoning effort)
• Web Framework: FastAPI — Modern async web framework with automatic API documentation
• Server: Uvicorn — Lightning-fast ASGI server for production-grade performance
• Templating: Jinja2 — Dynamic HTML template rendering for the web UI
• Configuration: YAML-based configuration for LLM models, parameters, and system thresholds

---

Setup

Prerequisites

• Python 3.10+ (recommended: 3.11 or later for optimal performance)
• Groq API key — Required for all LLM operations (free tier available)
• Tavily API key — Optional, only needed if using web search functionality
• Virtual environment manager — venv, pipenv, or conda

Install

1. Clone the repository and navigate to the project:

   cd Agentic-Chatbot

2. Create and activate a virtual environment:

   python -m venv agent_env
   # On Windows:
   agent_env\Scripts\activate
   # On macOS/Linux:
   source agent_env/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

Environment Configuration

Create a .env file in the project root with your API credentials:

# Required
GROQ_API_KEY=gsk_your_groq_api_key_here

# Optional (for web search functionality)
TAVILY_API_KEY=your_tavily_api_key_here

Important: Add .env to .gitignore to prevent accidental credential exposure.

---

Run

Web Application (Recommended)

Launch the interactive web UI from the project root:

uvicorn src.api.app:app --reload --host 0.0.0.0 --port 8000

Then open your browser to:

http://127.0.0.1:8000

The web interface provides:

• Real-time streaming responses
• Multi-turn conversation history
• Thread-based session management
• Responsive design for desktop and mobile

Command-Line Interface

For local testing and development, use the async CLI loop:

python run_cli.py

Requirements:

• Ensure PYTHONPATH includes the project root
• All dependencies from requirements.txt must be installed
• API keys configured in .env

---

Repository structure

Agentic-Chatbot/
├── src/
│   ├── api/                 # FastAPI application & endpoints
│   ├── graph/               # LangGraph workflow definition
│   ├── nodes/               # Pipeline stage implementations
│   ├── state/               # State schema & data models
│   ├── llm/                 # LLM client & model registry
│   ├── memory/              # Memory management & summarization
│   ├── tools/               # Tool definitions & registry
│   ├── prompts/             # LLM prompt templates
│   ├── logger/              # Logging configuration
│   └── utils/               # Utility functions
├── config/
│   └── llm_info.yaml        # Model configurations & parameters
├── templates/               # Jinja2 HTML templates
├── static/                  # CSS, JavaScript, assets
├── tests/                   # Test files & notebooks
├── requirements.txt         # Python dependencies
└── README.md               # This file

Key modules explained

Module	Purpose
src/graph/builder.py	Defines LangGraph state machine and conditional routing logic
src/state/schema.py	Defines AgenticChatState and all structured output types
src/nodes/	Implements each pipeline stage (analyzer, planner, executor, etc.)
src/memory/	Token-aware memory management and conversation summarization
src/llm/client.py	Groq LLM client wrapper with streaming support
src/tools/registry.py	Dynamic tool registration and dispatch system
config/llm_info.yaml	Centralized configuration for all LLM models & parameters
src/api/app.py	FastAPI server with SSE streaming endpoints

---

Disclaimer

Important Considerations:

• LLM outputs may contain inaccuracies or hallucinations; always verify critical information independently
• Web search results depend on external service availability and may include outdated information
• Respect website robots.txt policies, terms of service, and applicable laws when using search or automation tools
• API usage may incur costs depending on your plan—monitor API quotas and billing

---

Contributing & Support

Contributions are welcome! Please feel free to:

• Report issues or request features via GitHub Issues
• Submit pull requests with improvements or bug fixes
• Share your use cases and feedback

For questions or support, open a discussion in the repository.

---

License

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