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:

fromagentic.tools.knowledge_tools_serverimportrefresh_vector_storerefresh_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

fromagentic.workflowimportinvoke_workflowresult=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

fromutilsimportchat_interfacefromagentic.workflowimportorchestratorchat_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