AI Helpdesk Ticketing System - Using Antigravity

-

🤖 Building an AI Helpdesk Ticketing System

A Complete Guide — From Zero to a Working AI-Powered Support System using Google Gemini, FastAPI & Vanilla JavaScript

📌 What Is This Application?

Imagine walking into a company and telling the IT helpdesk: "I forgot my password" — and within seconds, an AI assistant understands your problem, asks for your username, generates a password reset link, and hands it back to you in a friendly message. That's exactly what we built.

This AI Helpdesk Ticketing System is an end-to-end web application that uses Google's Gemini AI to act as an intelligent IT support agent. Instead of waiting for a human support representative, users can chat with an AI that:

  • 🔑 Resets passwords — Generates a mock password reset link for the user.
  • 🔐 Diagnoses login issues — Checks if an account is locked or the password is simply wrong.
  • 📅 Shows leave balance — Looks up PTO, sick days, and personal days for an employee.

The AI doesn't just spit out canned responses — it classifies the user's problem, asks for missing information (like their username or employee ID), calls the right tool, and formats a natural, human-like reply. It even remembers context within a conversation, so you don't have to repeat yourself!

🏗️ How the Application Works — The Big Picture

The application has three layers that work together:

┌─────────────────────────┐         ┌──────────────────────────┐
│                         │  HTTP   │                          │
│   FRONTEND (Browser)    │ ──────▶ │   BACKEND (FastAPI)      │
│   HTML + CSS + JS       │         │   Python Server          │
│   Port 3000             │ ◀────── │   Port 8000              │
│                         │  JSON   │                          │
└─────────────────────────┘         └────────────┬─────────────┘
                                                 │
                                                 │ Sends user message
                                                 ▼
                                    ┌──────────────────────────┐
                                    │   GEMINI AI AGENT        │
                                    │   • Classifies the issue │
                                    │   • Asks clarifications  │
                                    │   • Calls the right tool │
                                    │   • Sends back response  │
                                    └────────────┬─────────────┘
                                                 │
                                                 │ Calls functions
                                                 ▼
                                    ┌──────────────────────────┐
                                    │   TOOLS (Python funcs)   │
                                    │   • Password Reset       │
                                    │   • Account Status Check │
                                    │   • Leave Balance Lookup │
                                    └──────────────────────────┘

In simple words:

  1. The user types a message in the chat UI (Frontend).
  2. The message is sent to the FastAPI server (Backend) via an HTTP POST request.
  3. The backend passes the message to the Gemini AI Agent, which figures out what the user needs.
  4. If the agent needs more info (like a username), it asks. If it has everything, it calls the right tool.
  5. The tool returns data (e.g., a reset link), and the agent formats a friendly response.
  6. The response travels back through the backend to the frontend, where it's displayed.

🔨 Step-by-Step: How It Was Built

Step 1 — Project Structure

We created a clean folder structure separating concerns:

helpdesk-ai/
├── backend/
│   ├── main.py              ← FastAPI server
│   ├── agent.py             ← Gemini AI agent
│   ├── tools.py             ← 3 custom tool functions
│   ├── requirements.txt     ← Python dependencies
│   └── .env.template        ← API key placeholder
├── frontend/
│   ├── index.html           ← Chat UI
│   ├── style.css            ← Dark-mode styling
│   └── app.js               ← Frontend logic
├── .gitignore
└── README.md

Step 2 — Building the Tools (The AI's "Skills")

Before building the AI agent, we first created the three tools that the agent can use. Think of these as the "skills" the AI has at its disposal. Each tool is a simple Python function:

📄 backend/tools.py

Function What It Does Input
trigger_password_reset() Generates a mock password reset link with a unique token username
check_account_status() Checks if the account is locked or active, with recommendations username
get_leave_balance() Returns a detailed leave balance table (PTO, sick, personal days) employee_id

Key insight: Each function has a detailed docstring (the description inside triple quotes). The Gemini SDK reads these docstrings to understand when and how to use each tool — this is how the AI "learns" its skills without any additional configuration!

Step 3 — Creating the AI Agent (The Brain)

This is the most exciting part. We used the Google GenAI Python SDK (google-genai) to create a conversational AI agent powered by Gemini 2.5 Flash.

📄 backend/agent.py — Here's what happens inside:

  1. Initialize the client — We connect to Google's API using our API key:
    client = genai.Client(api_key=GEMINI_API_KEY)
  2. Write a System Instruction — This is a detailed prompt telling the AI who it is, what tools it has, and how to behave. We tell it:
    • You are an IT Helpdesk Support Agent
    • Classify tickets into: password reset, login issue, or leave balance
    • Ask for missing info (username/employee ID) before calling tools
    • Be concise, friendly, and professional
  3. Create a Chat Session — Using client.chats.create(), we create a stateful conversation. This means the AI remembers what was said earlier in the chat: 
    chat = client.chats.create(
    model="gemini-2.5-flash",
    config=types.GenerateContentConfig(
        system_instruction=SYSTEM_INSTRUCTION,
        tools=[trigger_password_reset, 
               check_account_status, 
               get_leave_balance],
        temperature=0.3,
    ),
)
  4. Automatic Function Calling (AFC) — This is the magic. When the AI decides it needs to call a tool, the SDK automatically executes the Python function, feeds the result back to the model, and produces a final text response — all in one chat.send_message() call!
💡 Why is this "agentic"? Unlike a simple chatbot that just generates text, our agent can take actions — it decides which tool to call, executes it, interprets the result, and formulates a response. This loop of Reason → Act → Observe → Respond is what makes it an "agent."

Step 4 — Building the FastAPI Backend (The Server)

📄 backend/main.py

The backend is the bridge between the frontend and the AI agent. We used FastAPI, a modern Python web framework, to create a REST API.

Key components:

  • CORS Middleware — Since the frontend runs on localhost:3000 and the backend on localhost:8000, browsers block requests between different origins by default. We added CORS middleware to explicitly allow this cross-origin communication.
  • POST /api/ticket — The main endpoint. It accepts a JSON body with the user's message and a session ID, passes it to the Gemini agent, and returns the AI's response.
  • GET /api/health — A simple health check to verify the server is running.
  • Session Management — Each conversation gets a unique session_id. The backend stores chat sessions in memory so the AI maintains context across multiple messages.

Request/Response flow:

→ POST /api/ticket
  Body: { "message": "I forgot my password", 
          "session_id": "sess_abc123" }

← Response: 
  { "response": "I'd be happy to help! What is your username?",
    "session_id": "sess_abc123" }

Step 5 — Crafting the Frontend (The Chat UI)

The frontend is built with pure HTML, CSS, and JavaScript — no frameworks, no build tools, no complexity. Just three files that create a premium, polished experience.

📄 frontend/index.html — The structure:

  • A header with the app logo, name, online/offline status, and a "New Chat" button
  • A scrollable messages area with a welcome message
  • Three quick-action chips ("Reset Password", "Login Issue", "Leave Balance")
  • A text input area with a send button

📄 frontend/style.css — The design features:

  • 🌙 Dark mode — Deep navy-to-charcoal gradient background
  • ✨ Glassmorphism — Frosted glass effects with backdrop-filter: blur()
  • 🎨 Animated background orbs — Three floating, blurred circles that drift slowly
  • 💬 Message animations — User messages slide in from the right, AI messages from the left
  • ⏳ Typing indicator — Three bouncing dots while waiting for the AI response
  • 🌈 Gradient accents — Purple-to-violet gradients on buttons, avatars, and the header

📄 frontend/app.js — The logic handles:

  • Generating a random session ID per browser tab
  • Sending messages to the backend API via fetch()
  • Rendering messages with basic Markdown formatting (bold, code, links)
  • Auto-resizing the textarea as you type
  • Health checking the backend on page load
  • Error handling with toast notifications

Step 6 — Configuration & Environment Setup

Security best practice: we never hardcode API keys. Instead:

  1. Created a .env.template file with a placeholder: GEMINI_API_KEY=your-key-here
  2. The user copies this to .env and fills in their actual key
  3. The Python backend loads it using python-dotenv
  4. A .gitignore ensures .env is never committed to GitHub

💬 How a Conversation Actually Flows

Here's a real example of how the AI handles a multi-turn password reset conversation:

I forgot my password, how to reset it?
I'd be happy to help you reset your password! 👋

Could you please provide me with your username or email address so I can initiate the reset process?
john.doe@company.com
✅ Password reset initiated!

A reset link has been sent to john.doe@company.com.
The link will expire in 30 minutes.

Is there anything else I can help you with?

Notice how the agent first asked for the username (because the user didn't provide it), and only then called the trigger_password_reset tool. The AI remembered the context from the first message and connected it with the username provided in the second message. This is the power of stateful, multi-turn conversations.

🛠️ Technology Stack

Layer Technology Why We Chose It
AI Model Gemini 2.5 Flash Fast, smart, supports function calling natively
AI SDK google-genai (Python) Official Google SDK with auto function calling & chat sessions
Backend FastAPI + Uvicorn Modern, async, auto-generates API docs, built-in validation
Frontend Vanilla HTML/CSS/JS Zero dependencies, no build step, instant setup
Environment python-dotenv Securely loads API keys from .env files
Version Control Git + GitHub Industry standard for source code management

🧠 Key Concepts Explained Simply

🤖 What is an "AI Agent"?

A regular chatbot just generates text. An AI agent can actually do things — it can call functions, access databases, send emails, etc. Our agent reasons about the problem, decides which tool to use, executes it, and uses the result to answer the user. This Reason → Act → Observe → Respond loop is what makes it "agentic."

🔧 What is "Function Calling"?

Function calling is a feature where the AI model doesn't just generate text — it can also output structured requests to call specific functions. The google-genai SDK's Automatic Function Calling (AFC) takes this further: it automatically executes the function, feeds the result back to the model, and repeats until a final text answer is produced — all in one API call.

🌐 What is "CORS"?

Cross-Origin Resource Sharing is a browser security feature. When your frontend (port 3000) tries to talk to your backend (port 8000), the browser blocks it because they're on different "origins." CORS middleware on the backend says "I trust requests from these specific origins" — allowing the communication to go through.

💾 What is "Session Management"?

Each conversation gets a unique session_id. The backend stores the Gemini chat session in memory, so when the user sends a follow-up message, the AI has the full conversation history. This is how the agent "remembers" that you're asking about a password reset when you provide your username in the next message.

🚀 How to Run It Yourself

Prerequisites: Python 3.10+, a web browser, and a Gemini API key (free).

# 1. Clone the repo
git clone https://github.com/Augmencord/helpdesk-ai.git
cd helpdesk-ai

# 2. Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1          # Windows
source .venv/bin/activate              # macOS/Linux

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

# 4. Configure API key
cp backend/.env.template backend/.env
# Edit backend/.env and add your GEMINI_API_KEY

# 5. Start the backend (Terminal 1)
uvicorn backend.main:app --reload --port 8000

# 6. Start the frontend (Terminal 2)
cd frontend
python -m http.server 3000

# 7. Open http://localhost:3000 in your browser!

📦 Get the Source Code

The complete source code is available on GitHub:

⭐ View on GitHub — Augmencord/helpdesk-ai

✨ Conclusion

Building an AI-powered helpdesk system is no longer rocket science. With Google's Gemini model and the google-genai SDK, you can create intelligent agents that don't just chat — they take action. The entire application took just a handful of files:

  • 3 Python files for the backend (server + agent + tools)
  • 3 web files for the frontend (HTML + CSS + JS)
  • 2 config files (requirements.txt + .env.template)
  • 1 README documenting everything

The key takeaway? Function calling transforms AI from a text generator into a capable assistant. By defining simple Python functions with clear docstrings, you give the AI model the ability to interact with external systems, databases, and APIs — and it figures out when and how to use them on its own.

Happy building! 🚀

Comments

Post a Comment

Popular posts from this blog

Feel of Google's Antigravity

-
  Feel of  Google's Antigravity What is Antigravity ? The easiest way to understand it is to think of a highly capable manager coordinating a team of specialists. Imagine a cricket captain who has played with the same team for years. He knows exactly who to turn to in different situations because he understands every player's strengths, weaknesses, and style of play. He relies on that knowledge to put the right person in the right role at the right time. Now imagine an exceptionally intelligent captain. Suppose your team is defending 160 in a T20 match. The captain does not sit down and work everything out alone. He speaks with the senior-most bowler about the death overs, asks the wicketkeeper what they are noticing about the opposition batters, checks with the spinner about how much the pitch is turning, and may even consult the coach about field placements. Everyone contributes a piece of the puzzle. The captain listens, keeps track of what is happening on the field, and th...
Read more

Intelligent Video Generation Platform: Draft 1

-
Project Showcase Building an AI-Powered CBSE Educational Video Generator Combining the intelligence of the Gemini 2.5 Flash model with the beautiful visuals of Manim and FastAPI to create dynamic micro-lessons in under 3 minutes. View on GitHub The Vision: Educational Videos in Seconds Creating high-quality, engaging educational content for high school students is notoriously hard. Students are easily overwhelmed by abstract equations and dry textbook jargon. Standard slide decks are boring, and professional motion graphic animations require days of manual labor. To address this challenge, we built a fully automated CBSE Class 12 Storyboard Generator & Video Compiler . The workflow is simple: enter a CBSE curriculum topic (like Capacitors , DNA Replication , or Ma...
Read more

How to create your own CSV to Conversation Analyst using Python Pandas and a Language Model(here Gemini for demonstration)

-
Image
Staring at raw spreadsheets can be overwhelming and, let's be honest, a bit boring. But what if you could ask an AI to read your data files and explain them to you as if you were chatting over coffee? In this post, I'm going to show you exactly how to do that. We'll build a simple Python script that reads a dataset, crunches the basic math, and asks Google's Gemini AI to summarize it in plain English. I've also included the full code and a detailed PDF guide below! The Architecture: How It Works Think of this script as your personal digital analyst. Here is the step-by-step process of what's happening under the hood: Read the Data: It uses the pandas library to open a text or CSV file and formats it into a digital spreadsheet. Crunch the Numbers: It automatically grabs a snapshot of the data and calculates basic statistics (like the average, minimum, and maximum). Consult the AI: It feeds the raw data and mathematical results into a prom...
Read more