A conversational AI agent that assists customers with sales, technical, account, and billing queries. It combines Retrieval‐Augmented Generation (RAG), LangChain tool calls, conversation‐history persistence, and a human‐approval workflow for high‐risk requests.
- Python 3.13 (or compatible version)
- Ollama installed locally – see https://ollama.com/
- Git (optional, for cloning the repo)
- Chrome/Chromadb (embedded vector store; no external service required)
- Source Zip file extract the .zip file
-
Create a virtual environment & install dependencies
python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt
-
Configure environment variables Create a
.envfile in the project root (the same folder asmain.py). Example:# LLM configuration OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_MODEL=gemma2:2b # you can change this later # Logging level (DEBUG, INFO, WARNING, ERROR) LOG_LEVEL=INFO
Adjust the values to match the model you intend to use.
-
Pull the LLM model with Ollama
ollama pull qwen2.5:3b # or any other model you prefer
If you are using a different model, update
OLLAMA_MODELin.envaccordingly.
python -m mainYou will be prompted for a customer name and then can type queries. Type exit, quit or q to stop the console.
When a high‐risk request (e.g., refund, cancellation) is detected, the graph pauses and prints:
[!] *** SYSTEM PAUSED: ESCALATED TO SUPERVISOR ***
You must then type APPROVED or REJECTED. The decision is fed back into the graph, and the agent proceeds with the appropriate response.
| Feature | Description |
|---|---|
| RAG (Retrieval‐Augmented Generation) | Uses ChromaDB to store vectorized document chunks. On each query the relevant context is retrieved and supplied to the LLM. |
| Logging | Centralised logger (app/config/logging_config.py) writes INFO/DEBUG messages to console and logs/ directory for traceability. |
| Conversation History Database | app/database/memory_repository.py persists every interaction in a SQLite DB (memory.db). The memory_recall node can fetch past issues. |
| Services | app/services/support_agent.py orchestrates RAG, tool lookup, and final response generation. |
| Tool Helpers | Simple wrappers (@tool) for sales, technical, billing and account actions (e.g., recommend_plan, get_pricing, reset_password). All tools accept optional arguments (`str |
| Human‐Approval Node | app/nodes/approval.py detects high‐risk queries and pauses execution for a supervisor decision, returning a dict so LangGraph no longer raises InvalidUpdateError. |
| Graph Visualization | The compiled LangGraph workflow automatically creates langgraph_workflow.png for a visual overview. |
- Default (local):
qwen2.5:3b(or any Ollama‐compatible model you pull). You can switch to another model by editingOLLAMA_MODELin.env(e.g.,llama3:8b,mistral:7b). - The README assumes the low‐cost Ollama model for quick prototyping, but the architecture works with any OpenAI‐compatible or LangChain provider.
- Add new tools – create a file under
app/tools/with an@tooldecorated function and expose it in the appropriate node. - Custom prompts – modify the prompt strings in
app/nodes/*.pyto tailor tone or include additional business rules. - Replace Chroma with an external vector store – update
app/rag/vector_db_service.pyto initialise the desired backend. - Deploy – containerise the app with Docker, expose the Ollama API, and point
OLLAMA_BASE_URLto the remote host.
- Pydantic validation errors – ensure tool arguments are optional (
str | None = None). This repo now follows that pattern. - InvalidUpdateError – the
human_approvalnode now returns a dict; make sure any custom interrupt nodes do the same. - Empty model output – verify that the prompt always contains either a textual response or a tool call; the
run_support_agentguard (if not response.tool_calls) handles the non‐tool path.