# SMIU AI Assistant
An AI-powered conversational assistant built with **Chainlit** and the **OpenAI Agents SDK**. The application uses a triage agent to understand user requests and route them to specialized agents for billing and refund-related queries.
## Features
* 🤖 AI-powered conversational interface
* 💬 Interactive chat UI powered by Chainlit
* 🧠 Triage agent for intelligent request routing
* 💳 Dedicated Billing Agent for billing-related questions
* 💰 Dedicated Refund Agent for refund-related requests
* 📦 Specialized refund handling for:
* Custom refund requests
* Damaged item refunds
* Late delivery refunds
* 🔄 Agent-to-agent handoffs using the OpenAI Agents SDK
* 📝 Conversation history maintained during the chat session
* 🔐 Environment variables used for API configuration
## How It Works
The application follows a simple agent-routing architecture:
User
│
▼
Triage Agent
│
├──► Billing Agent
│
├──► Custom Refund Handoff
│ │
│ └──► Refund Agent
│
├──► Damaged Item Refund Handoff
│ │
│ └──► Refund Agent
│
└──► Late Delivery Refund Handoff
│
└──► Refund Agent
### Agent Responsibilities
#### 1. Triage Agent
The **Triage Agent** is the main entry point of the application. It receives the user's message, understands the intent, and decides which specialized agent should handle the request.
For example:
* Billing question → Billing Agent
* Custom refund request → Custom Refund Agent
* Damaged item → Damaged Item Refund Agent
* Late delivery → Late Delivery Refund Agent
#### 2. Billing Agent
The **Billing Agent** handles billing-related questions only.
Examples:
* Payment issues
* Billing information
* Charges
* Invoices
* Payment-related questions
#### 3. Custom Refund Agent
The **Custom Refund Agent** handles general or custom refund requests that do not specifically fall into the damaged-item or late-delivery categories.
#### 4. Damaged Item Refund Agent
The **Damaged Item Refund Agent** handles refund requests where the customer received a damaged or defective item.
#### 5. Late Delivery Refund Agent
The **Late Delivery Refund Agent** handles refund-related requests caused by delayed deliveries.
## Agent Handoffs
The project uses the **OpenAI Agents SDK handoff mechanism** to transfer conversations between agents.
Instead of having one agent handle every type of request, the triage agent delegates the conversation to the most appropriate specialized agent.
This provides:
* Clear separation of responsibilities
* Better organization
* More focused agent instructions
* Easier maintenance
* Scalable agent architecture
## Project Structure
SMIU-AI-Assistant/
│
├── main.py
├── handoff.py
├── agents.py
├── requirements.txt
├── .env
├── .gitignore
└── README.md
The exact file structure may vary depending on the current implementation.
## Technologies Used
* **Python** – Main programming language
* **Chainlit** – Conversational web interface
* **OpenAI Agents SDK** – Agent creation, orchestration, and handoffs
* **OpenAI API** – AI model functionality
* **python-dotenv** – Environment variable management
## Installation
Clone or download the project and open the project directory in the terminal.
Create and activate a virtual environment:
python -m venv .venv
Activate it on Windows:
.venv\\Scripts\\activate
Install the required dependencies:
pip install -r requirements.txt
## Environment Variables
Create a .env file in the project root and add your OpenAI API key:
OPENAI\_API\_KEY=your\_api\_key\_here
Make sure the .env file is not committed to GitHub.
Add it to .gitignore:
.env
.venv/
\_\_pycache\_\_/
## Running the Application
Start the Chainlit application using:
chainlit run main.py
After starting the application, Chainlit will provide a local URL where you can open the AI assistant in your browser.
For example:
http://localhost:8000
## Example Conversations
### Billing Request
User:
Why was I charged twice?
Triage Agent:
Routes the request to the Billing Agent.
Billing Agent:
Handles the billing-related question.
### Damaged Item Refund
User:
My product arrived damaged. I want a refund.
Triage Agent:
Routes the request to the Damaged Item Refund Agent.
Damaged Item Refund Agent:
Handles the damaged-item refund request.
### Late Delivery Refund
User:
My order arrived very late and I want a refund.
Triage Agent:
Routes the request to the Late Delivery Refund Agent.
Late Delivery Refund Agent:
Handles the late-delivery refund request.
### Custom Refund
User:
I want to request a refund for my order.
Triage Agent:
Routes the request to the Custom Refund Agent.
Custom Refund Agent:
Handles the custom refund request.
## Conversation Flow
The overall conversation flow can be summarized as:
User Message
│
▼
Triage Agent
│
├───────────────┐
│ │
▼ ▼
Billing Refund Request
Agent │
▼
Refund Category
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Custom Damaged Late
Refund Item Delivery
│ │ │
└─────────────┼─────────────┘
▼
Specialized
Refund Agent
## Key Concepts Demonstrated
This project demonstrates several important concepts from the OpenAI Agents SDK:
* Agent creation
* Agent instructions
* Agent orchestration
* Agent handoffs
* Specialized agents
* Intent-based routing
* Conversational state
* Environment variable configuration
* Chainlit integration
## Purpose
The purpose of this project is to demonstrate how multiple AI agents can work together to build a structured customer-support assistant.
Rather than relying on a single general-purpose agent, the system separates responsibilities between specialized agents and uses a triage agent to route each request appropriately.
## Future Improvements
Possible future improvements include:
* 🔐 User authentication
* 🗄️ Database integration
* 📊 Conversation analytics
* 📧 Email notifications
* 🎫 Customer support ticket creation
* 🧾 Real-time order lookup
* 💳 Integration with payment systems
* 📦 Integration with delivery/order tracking systems
* 🌐 Deployment to a cloud platform
* 🧠 More specialized support agents
## License
This project is developed for educational and practical purposes.