Customer Support Agent (AI-Powered Triage & HITL Escalation)

This project implements a Customer Support Agent, a Generative AI-powered email classification and routing system. It is built using the Google Agent Development Kit (ADK) and demonstrates how to integrate LLM decision-making nodes with conditional Human-in-the-Loop (HITL) workflows.

---

Overview & Logic Flow

The system processes incoming customer emails through a stateful graph-based workflow. It leverages Gemini to classify intent and handle routing:

graph TD
    START([Incoming Email Text]) --> NodeProcess[process_email Node]
    NodeProcess --> NodeLLM[analyst_agent LLM classification]
    NodeLLM --> CheckCrit{Gemini output is CRITICO?}
    
    CheckCrit -->|No: NORMALE| AutoApprove[Auto-Approve: Send courtesy reply]
    CheckCrit -->|Yes: CRITICO| HITL[Human-in-the-Loop: Yield escalation_review]
    
    HITL --> WaitReply[Wait for Supervisor Decision]
    WaitReply --> Resume[Workflow Resumes]
    
    Resume --> Finalize[Output final action: 'Pratica critica chiusa. Decisione operatore: risposta']

Loading

1. Intent Analysis & Classification (LLM)

Every email is passed to the analyst_agent (powered by the integrated Gemini model) with the following instructions:

"Analizza questa email. Rispondi SOLO con la parola CRITICO se il cliente è arrabbiato, minaccia azioni legali o chiede esplicitamente un rimborso. Altrimenti rispondi NORMALE."

2. Auto-Approval for Normal Inquiries

If Gemini returns "NORMALE", the agent auto-approves the request and generates a boilerplate draft reply.

• Example Input: "Can you check the delivery status of order #12345?"
• Response: "Email normale. Generata e inviata bozza di risposta di cortesia."

3. Escalation Review (Human-in-the-Loop)

If Gemini returns "CRITICO" (due to anger, legal threats, or refund requests), the workflow pauses by yielding a RequestInput object with the ID escalation_review. The system suspends its state and prompts a human supervisor for instructions:

• Example Input: "The product arrived broken! Refund my money immediately or I will take legal action!"
• Prompt emitted: "Attenzione: rilevata email critica o richiesta di rimborso. Come procediamo? (es. Autorizza / Rifiuta)"
• Workflow Resumption: Once the supervisor submits a decision (e.g., "Autorizza" or "Rifiuta"), the workflow resumes and outputs: "Pratica critica chiusa. Decisione operatore: Autorizza".

---

Project Setup

Synchronize project dependencies inside the virtual environment:

# Verify packages inside virtual environment
..\.venv\Scripts\agents-cli install

This updates the environment with all libraries defined in the project's pyproject.toml file.

---

Local Verification & Simulation

To test the system without incurring costs or hitting Google Cloud Vertex AI connection errors (especially in environments where the default cloud project is deleted or inaccessible), we have provided a mocked simulation script:

Run Simulation Test

Run the test script to simulate both the auto-approval flow (normal email) and the human-in-the-loop escalation + resumption flow (refund/critical email):

# Executed via the virtual environment python interpreter
.venv\Scripts\python test_local_support.py

Expected Output

When running the script, you should see:

1. TEST 1 (Normal): Classified as NORMALE, returning the automated courtesy response.
2. TEST 2 (Critical): Classified as CRITICO, prompting the operator for action, pausing in a suspended state, and then outputting the final supervisor decision upon simulated resumption.