In this tutorial, I am building a practical AI-powered Telecom Customer Support Agent using Python, FastAPI, Google Cloud, Vertex AI and Gemini.
The goal is to build an AI system that can understand a telecom customer's problem and then:
Analyze whether there is a legitimate upsell opportunity.
Recommend the most appropriate telecom plan.
Generate a personalized customer offer.
The project is called:
GlobalNet Support Agent
This is not just a chatbot. The objective is to build a modular AI-agent architecture that can later be extended with:
RAG
Firestore
Customer data
Plan knowledge base
Email notifications
Cloud Run
Cloud Scheduler
Monitoring
Multiple AI agents
Kubernetes integration
This article covers the implementation completed so far.
1. Project Architecture
The current architecture is:
Customer
|
v
FastAPI /support
|
v
+---------------+
| Upsell Agent |
+---------------+
|
v
Gemini AI
|
v
+---------------+
| Plan Agent |
+---------------+
|
v
Gemini AI
|
v
+---------------+
| Offer Agent |
+---------------+
|
v
Personalized OfferThe current technology stack is:
Python
FastAPI
Pydantic
Google Gen AI SDK
Google Cloud Vertex AI
Gemini 2.5 Flash
PowerShell
VS Code2. Final Directory Structure So Far
The project currently has the following structure:
GlobalNet-Support-Agent-GCP/
│
├── app/
│ ├── __init__.py
│ │
│ ├── main.py
│ │
│ ├── agents/
│ │ ├── __init__.py
│ │ ├── upsell_agent.py
│ │ ├── plan_agent.py
│ │ └── offer_agent.py
│ │
│ ├── services/
│ │ ├── __init__.py
│ │ ├── vertex_ai.py
│ │ ├── rag.py
│ │ ├── firestore.py
│ │ └── email.py
│ │
│ └── models/
│ └── customer.py
│
├── jobs/
│ └── scan_inactive_customers.py
│
├── data/
│ └── plans/
│
├── test_vertex.py
│
├── requirements.txt
├── Dockerfile
├── .dockerignore
└── README.mdSome directories such as rag.py, firestore.py, email.py, and scheduled jobs are part of the planned architecture and will be implemented in later parts.
3. Create the GCP Project
The Google Cloud project used for this application is:
globalnet-support-agentSet the project using the Google Cloud CLI:
gcloud config set project globalnet-support-agentExpected output:
Updated property [core/project].4. Enable Required Google Cloud APIs
The following APIs are required for the project:
gcloud services enable `
run.googleapis.com `
cloudbuild.googleapis.com `
artifactregistry.googleapis.com `
aiplatform.googleapis.com `
firestore.googleapis.com `
storage.googleapis.com `
cloudscheduler.googleapis.com `
secretmanager.googleapis.com `
logging.googleapis.comThese services will eventually provide:
Vertex AI
Cloud Run
Cloud Build
Artifact Registry
Firestore
Cloud Storage
Cloud Scheduler
Secret Manager
Cloud Logging5. Configure Google Cloud Authentication
For local development, Application Default Credentials can be configured using:
gcloud auth application-default loginThe project can also be configured as the quota project:
gcloud auth application-default set-quota-project globalnet-support-agent6. Configure Environment Variables
The application uses the following environment variables.
In PowerShell:
$env:GOOGLE_CLOUD_PROJECT="globalnet-support-agent"
$env:GOOGLE_CLOUD_LOCATION="asia-south1"These values are used by the Vertex AI service.
7. Vertex AI Service
Instead of putting Gemini code directly inside every agent, I created a reusable service.
File:
app/services/vertex_ai.pyCode:
from google import genai
from google.genai.types import GenerateContentConfig
import os
PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
LOCATION = os.environ.get(
"GOOGLE_CLOUD_LOCATION",
"asia-south1"
)
client = genai.Client(
vertexai=True,
project=PROJECT_ID,
location=LOCATION,
)
def generate_text(prompt: str) -> str:
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=prompt,
config=GenerateContentConfig(
temperature=0.2,
),
)
return response.textThis creates one reusable function:
generate_text()All AI agents can use this function.
8. Test Gemini Independently
Before connecting Gemini to FastAPI, I created:
test_vertex.pyCode:
from app.services.vertex_ai import generate_text
prompt = """
You are a telecom customer support AI.
A customer says:
"My internet is very slow and I need more bandwidth."
Explain whether there could be an upsell opportunity.
"""
print("Calling Gemini...")
result = generate_text(prompt)
print("\n===== GEMINI RESPONSE =====\n")
print(result)Run:
python test_vertex.pyIf everything is configured correctly, Gemini returns a response.
This is an important development practice:
First verify the AI service independently, then integrate it with the application.
9. FastAPI Application
The main API is:
app/main.pyFastAPI is used to expose the AI agent through an HTTP API.
The application starts with:
from fastapi import FastAPI
from pydantic import BaseModelThe FastAPI application is created using:
app = FastAPI(
title="GlobalNet Support Agent",
description="AI-powered telecom customer support agent",
version="1.0.0",
)10. Customer Request Model
The /support API receives customer information.
class SupportRequest(BaseModel):
customer_id: str
chat_text: str
loyalty_status: str
current_plan: str
current_plan_desc: str
tenure_months: int
customer_email: str
customer_name: str
call_type: strPydantic automatically validates this request.
11. Health Check API
The application contains a basic health endpoint:
@app.get("/health")
def health():
return {
"status": "healthy"
}Testing:
GET /healthExpected response:
{
"status": "healthy"
}This endpoint will become useful later for Cloud Run and production monitoring.
12. Root Endpoint
The root endpoint is:
@app.get("/")
def root():
return {
"status": "ok",
"service": "GlobalNet Support Agent",
"message": "API is running",
}13. Upsell Agent
The first AI agent is the:
Upsell AgentFile:
app/agents/upsell_agent.pyIts responsibility is to determine whether the customer's problem represents a genuine upgrade opportunity.
Complete code:
from app.services.vertex_ai import generate_text
def analyze_upsell(customer) -> str:
prompt = f"""
You are a telecom customer support upsell AI.
Analyze the customer information below.
Customer Information:
- Customer ID: {customer.customer_id}
- Customer Name: {customer.customer_name}
- Loyalty Status: {customer.loyalty_status}
- Current Plan: {customer.current_plan}
- Current Plan Description: {customer.current_plan_desc}
- Tenure: {customer.tenure_months} months
- Call Type: {customer.call_type}
Customer Message:
{customer.chat_text}
Determine:
1. What is the customer's main problem?
2. Is there a legitimate upsell opportunity?
3. Why is there or isn't there an opportunity?
4. What type of plan would be appropriate?
5. What should the support agent do next?
Important:
- Do not recommend an upgrade just to increase revenue.
- First determine whether the customer's problem could be
caused by a technical issue.
- If a technical issue is likely, recommend troubleshooting first.
- Only recommend an upsell when the customer's actual usage
justifies a higher plan.
Provide a clear and concise answer.
"""
return generate_text(prompt)14. Why the Upsell Agent Checks Technical Problems
This is important in a real telecom environment.
A customer saying:
"My internet is very slow."does not automatically mean:
Customer needs a bigger plan.The problem could be:
Router problem
|
Wi-Fi interference
|
Packet loss
|
DNS problem
|
ISP network problem
|
Congestion
|
Signal issue
|
Only then → insufficient bandwidthTherefore, the AI should not automatically try to sell something.
The prompt explicitly tells the AI:
Do not recommend an upgrade just to increase revenue.This makes the agent more customer-centric.
15. Plan Agent
The second agent is:
Plan AgentFile:
app/agents/plan_agent.pyIts responsibility is to select the most appropriate plan.
Complete code:
from app.services.vertex_ai import generate_text
def recommend_plan(customer, upsell_analysis: str) -> str:
prompt = f"""
You are a telecom plan recommendation AI.
Analyze the customer information and upsell analysis below.
Customer Information:
- Customer ID: {customer.customer_id}
- Customer Name: {customer.customer_name}
- Current Plan: {customer.current_plan}
- Current Plan Description: {customer.current_plan_desc}
- Loyalty Status: {customer.loyalty_status}
- Tenure: {customer.tenure_months} months
- Call Type: {customer.call_type}
Customer Message:
{customer.chat_text}
Upsell Analysis:
{upsell_analysis}
Available Example Plans:
1. BASIC
Speed: 100 Mbps
2. STANDARD
Speed: 300 Mbps
3. PREMIUM
Speed: 500 Mbps
4. ULTRA
Speed: 1 Gbps
Rules:
1. Do not recommend an upgrade just to increase revenue.
2. If the problem appears to be a technical issue, recommend
troubleshooting before upgrading.
3. If the customer genuinely needs more bandwidth, recommend
the lowest plan that can satisfy the requirement.
4. Consider the customer's current plan.
5. Consider the customer's stated usage.
6. Explain why the recommended plan is appropriate.
7. Mention the current plan.
8. Mention the recommended plan.
9. Keep the response concise and suitable for a support agent.
Return:
Current Plan:
Recommended Plan:
Reason:
Next Action:
"""
return generate_text(prompt)16. Example Plan Catalog
Currently the plans are hardcoded for learning purposes:
BASIC
100 Mbps
STANDARD
300 Mbps
PREMIUM
500 Mbps
ULTRA
1 GbpsLater, these values will not be hardcoded.
They will come from a real knowledge source:
Plan Agent
|
v
RAG
|
v
Plan Knowledge Base
|
v
GlobalNet PlansThis will be implemented in a future part.
17. Offer Agent
The third agent is:
Offer AgentFile:
app/agents/offer_agent.pyIts responsibility is to create a personalized offer.
Complete code:
from app.services.vertex_ai import generate_text
def generate_offer(customer, plan_recommendation: str) -> str:
prompt = f"""
You are a telecom customer retention and offer AI.
Analyze the customer information below and create an appropriate
personalized telecom offer.
Customer Information:
- Customer ID: {customer.customer_id}
- Customer Name: {customer.customer_name}
- Current Plan: {customer.current_plan}
- Current Plan Description: {customer.current_plan_desc}
- Loyalty Status: {customer.loyalty_status}
- Tenure: {customer.tenure_months} months
- Call Type: {customer.call_type}
Customer Message:
{customer.chat_text}
Plan Recommendation:
{plan_recommendation}
Offer Rules:
1. Do not create an offer if there is no legitimate upgrade
opportunity.
2. If a technical issue is likely, recommend troubleshooting
instead of an upgrade offer.
3. GOLD or higher loyalty customers may receive a stronger
retention benefit.
4. Long-tenure customers may receive a loyalty benefit.
5. Do not invent unrealistic discounts.
6. The offer should be simple and easy for a support agent
to explain to the customer.
7. Explain why the customer is receiving the offer.
8. The offer should match the recommended plan.
Return the result in this format:
Offer Decision:
Recommended Plan:
Monthly Benefit:
Loyalty Benefit:
Reason:
Agent Action:
Customer Message:
"""
return generate_text(prompt)18. Complete main.py
The current complete main.py is:
from fastapi import FastAPI
from pydantic import BaseModel
from app.agents.upsell_agent import analyze_upsell
from app.agents.plan_agent import recommend_plan
from app.agents.offer_agent import generate_offer
app = FastAPI(
title="GlobalNet Support Agent",
description="AI-powered telecom customer support agent",
version="1.0.0",
)
class SupportRequest(BaseModel):
customer_id: str
chat_text: str
loyalty_status: str
current_plan: str
current_plan_desc: str
tenure_months: int
customer_email: str
customer_name: str
call_type: str
@app.get("/")
def root():
return {
"status": "ok",
"service": "GlobalNet Support Agent",
"message": "API is running",
}
@app.get("/health")
def health():
return {
"status": "healthy"
}
@app.post("/support")
def support(request: SupportRequest):
# Step 1: Analyze upsell opportunity
upsell_result = analyze_upsell(request)
# Step 2: Recommend appropriate plan
plan_result = recommend_plan(
request,
upsell_result
)
# Step 3: Generate personalized offer
offer_result = generate_offer(
request,
plan_result
)
return {
"status": "success",
"customer_id": request.customer_id,
"customer_name": request.customer_name,
"upsell_analysis": upsell_result,
"plan_recommendation": plan_result,
"personalized_offer": offer_result,
}19. Start the Application
From the project root:
cd "C:\Users\Raj Kumar Gupta\Desktop\Raj\minikube\GlobalNet-Support-Agent-GCP"Set the environment variables:
$env:GOOGLE_CLOUD_PROJECT="globalnet-support-agent"
$env:GOOGLE_CLOUD_LOCATION="asia-south1"Start FastAPI:
uvicorn app.main:app --reloadExpected:
Uvicorn running on http://127.0.0.1:800020. Open Swagger
FastAPI automatically provides Swagger UI.
Open:
http://127.0.0.1:8000/docsYou should see:
GET /
GET /health
POST /support21. Test /support
Select:
POST /supportClick:
Try it outUse this request:
{
"customer_id": "1001",
"chat_text": "My internet is very slow and I need much higher bandwidth because I have many devices and use 4K streaming.",
"loyalty_status": "GOLD",
"current_plan": "BASIC",
"current_plan_desc": "100 Mbps",
"tenure_months": 48,
"customer_email": "your-email@example.com",
"customer_name": "Raj",
"call_type": "online"
}Click:
Execute22. What Happens Internally?
The request enters:
POST /supportThen:
SupportRequest
|
v
analyze_upsell()
|
v
Gemini
|
v
upsell_resultThen:
upsell_result
|
v
recommend_plan()
|
v
Gemini
|
v
plan_resultThen:
plan_result
|
v
generate_offer()
|
v
Gemini
|
v
offer_resultFinally:
JSON Response23. Final Response Structure
The API returns a structure similar to:
{
"status": "success",
"customer_id": "1001",
"customer_name": "Raj",
"upsell_analysis": "...",
"plan_recommendation": "...",
"personalized_offer": "..."
}The exact AI text will vary because Gemini generates the response dynamically.
24. Complete Request Flow
The complete flow is now:
+----------------+
| Customer |
+-------+--------+
|
v
+---------------+
| FastAPI |
| /support |
+-------+-------+
|
v
+-----------------------+
| Upsell Agent |
| |
| Is upgrade justified? |
+----------+------------+
|
v
+---------+
| Gemini |
+----+----+
|
v
+-----------------------+
| Plan Agent |
| |
| Which plan is best? |
+----------+------------+
|
v
+---------+
| Gemini |
+----+----+
|
v
+-----------------------+
| Offer Agent |
| |
| What offer should |
| we provide? |
+----------+------------+
|
v
+---------+
| Gemini |
+----+----+
|
v
+-----------------------+
| Final API Response |
+-----------------------+25. Why Use Multiple Agents?
Instead of creating one large prompt, the application separates responsibilities.
Upsell Agent
Answers:
Should we upgrade the customer?Plan Agent
Answers:
Which plan is appropriate?Offer Agent
Answers:
What personalized offer should we provide?This separation makes the application easier to:
Maintain
Test
Debug
Extend
Replace individual agents
Add business rules
Add RAG
Add databases
26. Current Limitations
The current implementation is a learning prototype.
There are several things that need to be improved before production.
Hardcoded plans
Currently:
BASIC → 100 Mbps
STANDARD → 300 Mbps
PREMIUM → 500 Mbps
ULTRA → 1 GbpsThese should come from a database or knowledge base.
Free-form AI responses
The agents currently return strings.
A production implementation should return structured JSON.
For example:
{
"upgrade_required": true,
"recommended_plan": "PREMIUM",
"reason": "Customer has multiple devices and 4K streaming requirements",
"next_action": "Offer plan upgrade"
}No RAG yet
The Plan Agent does not yet retrieve information from a real GlobalNet knowledge base.
No Firestore yet
Customer information is currently supplied directly through the API request.
No authentication
The API currently has no authentication or authorization.
No production monitoring
Cloud Logging, metrics and tracing still need to be integrated.
27. What We Will Build Next
The next stage will make the project significantly more realistic.
The planned architecture is:
Customer
|
v
FastAPI
|
v
Agent Orchestrator
|
+------------------+
| |
v v
Upsell Agent RAG System
| |
| v
| Plan Knowledge
| |
+--------+---------+
|
v
Plan Agent
|
v
Offer Agent
|
v
Firestore
|
v
Email Agent
|
v
Customer NotificationFuture components will include:
RAG
ChromaDB / Vector Database
Embeddings
Firestore
Customer Database
Plan Knowledge Base
Email Service
Cloud Run
Artifact Registry
Cloud Scheduler
Cloud Logging28. Learning Lessons From This Project
This project demonstrates several important Python and AI engineering concepts.
Python
We are learning:
Functions
Imports
Modules
Packages
Classes
Type validation
Virtual environments
Environment variables
Exception handlingFastAPI
We are learning:
REST API
Endpoints
POST requests
Pydantic models
Swagger
Health checks
API integrationGenerative AI
We are learning:
LLM integration
Prompt engineering
Agent design
Multi-agent architecture
Context passing
AI decision makingCloud
We are learning:
Google Cloud
Vertex AI
Cloud Run
Artifact Registry
Firestore
Cloud Scheduler
Secret Manager
Cloud Logging29. Conclusion
We have now created the first working version of the GlobalNet Support Agent.
The application can:
Receive customer request
↓
Analyze upsell opportunity
↓
Recommend a suitable plan
↓
Generate a personalized offer
↓
Return the result through REST APIThe most important design principle is that the AI should not simply try to sell a more expensive plan.
The system should first understand the customer's actual problem.
For example:
Customer:
"My internet is slow."
↓
AI investigates
↓
Could be technical issue?
|
YES ─────→ Troubleshoot first
|
NO
|
v
Does usage justify more bandwidth?
|
YES
|
v
Recommend appropriate plan
|
v
Generate personalized offer
No comments:
Post a Comment