UDA-Hub — Autonomous Knowledge Agent

A multi-agent customer-support automation system built with LangGraph — intelligent ticket classification, RAG-powered knowledge retrieval, tool-based action execution, and human escalation.

UDA-Hub is an agentic system that automates customer-support operations for CultPass, a (fictional) cultural-experiences subscription service. It uses a supervisor pattern in which a coordinating agent routes each ticket to the specialist agent best suited to resolve it, and escalates to a human when confidence is low.

It was built as a hands-on exploration of agentic AI engineering with LangChain and LangGraph.

Table of Contents

• Overview
• Architecture
• Prerequisites
• Installation
• Data Setup
• Usage
• Testing
• Project Structure
• Configuration
• Key Features
• Documentation
• License

Overview

The system handles a support ticket end to end:

• Classify the ticket by type, urgency, and intent
• Route it to the appropriate specialist agent
• Retrieve answers from a searchable knowledge base (RAG)
• Execute actions on user accounts and subscriptions via standardized tools
• Escalate complex or low-confidence issues to a human agent
• Learn from resolved tickets using long-term memory

Architecture

Supervisor pattern

User Ticket
    |
Classifier Agent  -->  Supervisor Agent
                            |
        +-------------------+-------------------+
        |                   |                   |
  Knowledge Agent      Action Agent       Escalation Agent
        |                   |                   |
   Supervisor           Supervisor             END
        |                   |
    Response             Response

Key components

1. Classifier Agent — analyzes tickets for type, urgency, and intent
2. Supervisor Agent — routes tickets and orchestrates the workflow
3. Knowledge Agent — searches the knowledge base using RAG with FAISS
4. Action Agent — executes operations via FastMCP tools
5. Escalation Agent — prepares summaries for human agents

Technologies

Layer	Technology
Orchestration	LangGraph (multi-agent state management)
LLM integration	LangChain
Language models	OpenAI GPT-4o / GPT-4o-mini
Retrieval	FAISS vector similarity search
Tooling	FastMCP (Model Context Protocol)
Storage	SQLite (CultPass + UDA-Hub databases)
Testing	pytest

Prerequisites

• Python 3.10 or higher
• An OpenAI API key
• ~2 GB of free disk space for vector stores

Installation

# 1. Clone the repository
git clone <your-repo-url>
cd uda-hub-agent

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

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure your API key
cp .env.example .env              # Windows: copy .env.example .env
# then edit .env and set OPENAI_API_KEY

The .env file is git-ignored and must never be committed.

Data Setup

The databases and vector stores are not committed to the repository — they are generated locally by the setup notebooks.

Step 1 — External database (CultPass)

jupyter notebook 01_external_db_setup.ipynb

Creates data/external/cultpass.db with users, subscriptions, experiences, and reservations.

Step 2 — Core database (UDA-Hub)

jupyter notebook 02_core_db_setup.ipynb

Creates data/core/udahub.db with accounts, tickets, and 14 knowledge articles spanning technical support, billing/refunds, account management, and experiences.

Step 3 — Vector store

The FAISS vector store is initialized automatically on first use. To build it manually:

from agentic.tools.knowledge_tools_server import refresh_vector_store
refresh_vector_store()

Usage

Option 1 — Demo notebook (recommended)

jupyter notebook 03_agentic_app.ipynb

Includes four demo scenarios, state inspection, a memory demonstration, and an optional interactive chat interface.

Option 2 — Programmatic

from agentic.workflow import invoke_workflow

result = invoke_workflow(
    user_message="How do I cancel my subscription?",
    ticket_id="ticket-001",
    external_user_id="f556c0",
    account_id="cultpass",
)

print(f"Classification: {result['classification']}")
print(f"Confidence:     {result['confidence']}")
print(f"Escalated:      {result['escalated']}")
print(f"Response:       {result['messages'][-1].content}")

Option 3 — Interactive chat

from utils import chat_interface
from agentic.workflow import orchestrator

chat_interface(orchestrator, "my-session-id")

Testing

pytest tests/                 # run the full suite
pytest tests/test_rag.py      # run a single file
pytest tests/ -v              # verbose output
pytest tests/ -m integration  # integration tests only (requires full setup)

Coverage spans database setup and schema validation, RAG retrieval and confidence scoring, individual agent behavior, workflow orchestration, and end-to-end integration scenarios.

Project Structure

uda-hub-agent/
├── 01_external_db_setup.ipynb    # CultPass database setup
├── 02_core_db_setup.ipynb        # UDA-Hub database setup
├── 03_agentic_app.ipynb          # Main demo application
├── agentic/
│   ├── agents/                   # Specialized agents
│   │   ├── classifier.py
│   │   ├── supervisor.py
│   │   ├── knowledge_agent.py
│   │   ├── action_agent.py
│   │   └── escalation_agent.py
│   ├── design/                   # Architecture documentation
│   ├── memory/                   # Long-term memory system
│   ├── rag/                      # Retrieval-Augmented Generation
│   ├── tools/                    # FastMCP tool servers
│   └── workflow.py               # LangGraph workflow orchestration
├── data/
│   ├── core/                     # UDA-Hub database (generated)
│   ├── external/                 # CultPass database + seed data files
│   ├── models/                   # SQLAlchemy models
│   └── vector_stores/            # FAISS indices (generated)
├── logs/                         # Runtime JSONL logs (generated)
├── tests/                        # pytest suite
├── utils.py                      # Utility functions
├── requirements.txt              # Python dependencies
├── .env.example                  # Environment variable template
└── README.md

Configuration

Models per agent

Agent	Model	Rationale
Supervisor	GPT-4o	Complex routing decisions
Classifier	GPT-4o-mini	Structured classification
Knowledge Agent	GPT-4o-mini	KB retrieval and synthesis
Action Agent	GPT-4o-mini	Tool execution
Escalation Agent	GPT-4o-mini	Summary generation

Thresholds and memory

• Auto-resolve when confidence ≥ 0.7, escalate when below
• Short-term memory — LangGraph MemorySaver, thread-based
• Long-term memory — FAISS vector store with OpenAI embeddings
• Embedding model — text-embedding-3-small (1536 dimensions)

Key Features

• Intelligent routing — the supervisor sends informational queries to the Knowledge Agent, action requests to the Action Agent, and complex/unclear tickets to the Escalation Agent.
• RAG-powered retrieval — semantic search over the knowledge base with FAISS, confidence scoring, and article citation in responses.
• Action execution via MCP tools — user lookup, subscription management, reservation management, and ticket status updates through standardized FastMCP tools.
• Multi-level memory — session memory within a conversation plus long-term memory of resolved tickets for learning from past interactions.
• Escalation logic — automatic escalation on low confidence, failed actions, explicit user requests, or complex multi-faceted issues.
• Structured logging — every agent decision, tool call, routing choice, and escalation is written to JSONL files under logs/ for full observability and auditability.

Documentation

In-depth design documentation lives in agentic/design/:

• architecture.md — system design and agent roles
• memory_strategy.md — short-term and long-term memory
• rag_documentation.md — vector store and retrieval details
• tools_documentation.md — MCP tool servers and usage

License

Released under the MIT License.

Acknowledgments

• LangChain / LangGraph — multi-agent framework
• OpenAI — language models
• CultPass — fictional customer used for realistic scenarios