From 5bb3905df8314097e7466797b05357b38d1bed32 Mon Sep 17 00:00:00 2001 From: ShubhamSaboo Date: Sat, 5 Jul 2025 19:37:45 -0500 Subject: [PATCH] feat: add customer support ticketing agent tutorial with structured output --- .../customer_support_ticket_agent/README.md | 110 ++++++++++++++++++ .../customer_support_agent}/.env.example | 0 .../customer_support_agent/__init__.py | 1 + .../customer_support_agent/agent.py | 46 ++++++++ .../requirements.txt | 0 .../{ => email_agent}/README.md | 6 +- .../email_generator_agent/.env.example | 3 + .../email_generator_agent/__init__.py | 0 .../email_generator_agent/agent.py | 0 .../email_agent/requirements.txt | 2 + 10 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/README.md rename google_adk_tutorials/structured_output_agent/{email_generator_agent => customer_support_ticket_agent/customer_support_agent}/.env.example (100%) create mode 100644 google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/__init__.py create mode 100644 google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/agent.py rename google_adk_tutorials/structured_output_agent/{ => customer_support_ticket_agent}/requirements.txt (100%) rename google_adk_tutorials/structured_output_agent/{ => email_agent}/README.md (95%) create mode 100644 google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/.env.example rename google_adk_tutorials/structured_output_agent/{ => email_agent}/email_generator_agent/__init__.py (100%) rename google_adk_tutorials/structured_output_agent/{ => email_agent}/email_generator_agent/agent.py (100%) create mode 100644 google_adk_tutorials/structured_output_agent/email_agent/requirements.txt diff --git a/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/README.md b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/README.md new file mode 100644 index 0000000..abf5ad5 --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/README.md @@ -0,0 +1,110 @@ +# 🎫 Customer Support Ticketing Agent with Structured Output + +A tutorial demonstrating how to implement a structured customer support ticketing system using Google's ADK (Agent Development Kit) framework. This example shows how to create type-safe, structured support tickets with priority levels, categories, and resolution estimates using Pydantic schemas and Gemini 2.0 Flash model. + +## Tutorial Features + +- 🎫 **Structured Support Tickets**: + - Learn how to create comprehensive support ticket schemas + - Understand priority levels and categorization + - See how to estimate resolution times + +- 🔧 **Advanced Schema Design**: + - Complex Pydantic models with enums and optional fields + - Proper field validation and descriptions + - Type-safe structured responses + +- 🎯 **Real-World Application**: + - Practical customer support use case + - Shows how to handle different types of support requests + - Demonstrates structured output for business processes + +- 📊 **Priority Management**: + - Four-tier priority system (Low, Medium, High, Critical) + - Automatic priority assignment based on issue description + - Category-based routing for different departments + +## How to Run + +1. **Setup Environment** + ```bash + # Clone the repository + git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git + cd awesome-llm-apps/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent + + # Install dependencies + pip install -r requirements.txt + ``` + +2. **Configure API Keys** + - Get Google AI API key from [Google AI Studio](https://aistudio.google.com/) + - Set up your API credentials for Gemini access + +3. **Run the Agent** + ```bash + # Start the ADK web interface from the root folder + cd google_adk_tutorials/structured_output_agent/customer_support_ticket_agent + adk web + ``` + Then: + 1. Open the web interface in your browser + 2. Select the "support_ticket_creator" agent + 3. Enter your support request (e.g., "I can't log into my account and I have an important meeting in 2 hours") + 4. The response will be a structured JSON with all ticket details + +## Tutorial Overview + +This tutorial demonstrates advanced structured output implementation in Google ADK: + +1. **Complex Schema Design**: Learn how to create sophisticated Pydantic models +2. **Enum Usage**: Understand how to use enums for constrained values +3. **Optional Fields**: See how to handle optional data with proper defaults +4. **Business Logic**: Learn how to implement real-world business processes + +## Code Structure + +- `customer_support_agent/agent.py`: Contains the main agent definition and SupportTicket schema +- `customer_support_agent/__init__.py`: Module initialization for easy imports + +## Support Ticket Schema + +The agent creates structured tickets with the following fields: + +- **title**: Concise summary of the issue +- **description**: Detailed problem description +- **priority**: Priority level (low, medium, high, critical) +- **category**: Department (Technical, Billing, Account, Product) +- **steps_to_reproduce**: Optional list of steps for technical issues +- **estimated_resolution_time**: Estimated time to resolve + +## Example Usage + +**Input**: "My payment failed and I'm getting charged twice for the same service" + +**Output**: +```json +{ + "title": "Duplicate payment charge issue", + "description": "Customer reports payment failure followed by duplicate charges for the same service", + "priority": "high", + "category": "Billing", + "steps_to_reproduce": null, + "estimated_resolution_time": "4-6 hours" +} +``` + +## Dependencies + +- `google-adk`: Google's Agent Development Kit +- `pydantic`: Data validation and settings management + +## How Structured Output Works + +This tutorial shows how Google ADK handles complex structured output: + +1. **Input Processing**: Takes natural language support requests +2. **Context Analysis**: Analyzes the issue severity and type +3. **Structured Generation**: Creates comprehensive tickets with all required fields +4. **Validation**: Ensures output matches the defined schema and business rules + +This approach demonstrates how to create reliable, business-ready structured responses in Google ADK applications. \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/email_generator_agent/.env.example b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/.env.example similarity index 100% rename from google_adk_tutorials/structured_output_agent/email_generator_agent/.env.example rename to google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/.env.example diff --git a/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/__init__.py b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/__init__.py new file mode 100644 index 0000000..c4be8e1 --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/__init__.py @@ -0,0 +1 @@ +from . import agent \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/agent.py b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/agent.py new file mode 100644 index 0000000..3896d2b --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/customer_support_agent/agent.py @@ -0,0 +1,46 @@ +from typing import List, Optional +from enum import Enum +from google.adk.agents import LlmAgent +from pydantic import BaseModel, Field + +class Priority(str, Enum): + LOW = "low" + MEDIUM = "medium" + HIGH = "high" + CRITICAL = "critical" + +class SupportTicket(BaseModel): + title: str = Field(description="A concise summary of the issue") + description: str = Field(description="Detailed description of the problem") + priority: Priority = Field(description="The ticket priority level") + category: str = Field(description="The department this ticket belongs to") + steps_to_reproduce: Optional[List[str]] = Field( + description="Steps to reproduce the issue (for technical problems)", + default=None + ) + estimated_resolution_time: str = Field( + description="Estimated time to resolve this issue" + ) + +root_agent = LlmAgent( + name="customer_support_agent", + model="gemini-2.5-flash", + description="Creates structured support tickets from user reports", + instruction=""" + You are a support ticket creation assistant. + + Based on user problem descriptions, create well-structured support tickets with appropriate priority levels, categories, and resolution estimates. + + IMPORTANT: Response must be valid JSON matching the SupportTicket schema with these fields: + - "title": Concise summary of the issue + - "description": Detailed problem description + - "priority": One of "low", "medium", "high", or "critical" + - "category": Department (e.g., "Technical", "Billing", "Account", "Product") + - "steps_to_reproduce": List of steps (for technical issues) or null + - "estimated_resolution_time": Estimated resolution time (e.g., "2-4 hours", "1-2 days") + + Format your response as valid JSON only. + """, + output_schema=SupportTicket, + output_key="support_ticket" +) \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/requirements.txt b/google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/requirements.txt similarity index 100% rename from google_adk_tutorials/structured_output_agent/requirements.txt rename to google_adk_tutorials/structured_output_agent/customer_support_ticket_agent/requirements.txt diff --git a/google_adk_tutorials/structured_output_agent/README.md b/google_adk_tutorials/structured_output_agent/email_agent/README.md similarity index 95% rename from google_adk_tutorials/structured_output_agent/README.md rename to google_adk_tutorials/structured_output_agent/email_agent/README.md index a1fcafe..e79ee2d 100644 --- a/google_adk_tutorials/structured_output_agent/README.md +++ b/google_adk_tutorials/structured_output_agent/email_agent/README.md @@ -1,4 +1,4 @@ -# 📧 Structured Output in Google ADK +# 📧 Email Generation Agent with Structured Output A tutorial demonstrating how to implement structured output using Google's ADK (Agent Development Kit) framework. This example uses an email generator agent to show how to create type-safe, structured responses with Pydantic schemas and Gemini 2.5 Flash model. @@ -25,7 +25,7 @@ A tutorial demonstrating how to implement structured output using Google's ADK ( ```bash # Clone the repository git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git - cd awesome-llm-apps/google_adk_tutorials/structured_output_agent/email_generator_agent + cd awesome-llm-apps/google_adk_tutorials/structured_output_agent/email_agent # Install dependencies pip install -r requirements.txt @@ -38,7 +38,7 @@ A tutorial demonstrating how to implement structured output using Google's ADK ( 3. **Run the Agent** ```bash # Start the ADK web interface from the root folder - cd google_adk_tutorials/structured_output_agent + cd google_adk_tutorials/structured_output_agent/email_agent adk web ``` Then: diff --git a/google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/.env.example b/google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/.env.example new file mode 100644 index 0000000..f5cfcfb --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/.env.example @@ -0,0 +1,3 @@ +# If using Gemini via Google AI Studio +GOOGLE_GENAI_USE_VERTEXAI=False +GOOGLE_API_KEY="your-api-key" \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/email_generator_agent/__init__.py b/google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/__init__.py similarity index 100% rename from google_adk_tutorials/structured_output_agent/email_generator_agent/__init__.py rename to google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/__init__.py diff --git a/google_adk_tutorials/structured_output_agent/email_generator_agent/agent.py b/google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/agent.py similarity index 100% rename from google_adk_tutorials/structured_output_agent/email_generator_agent/agent.py rename to google_adk_tutorials/structured_output_agent/email_agent/email_generator_agent/agent.py diff --git a/google_adk_tutorials/structured_output_agent/email_agent/requirements.txt b/google_adk_tutorials/structured_output_agent/email_agent/requirements.txt new file mode 100644 index 0000000..53c77a2 --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/email_agent/requirements.txt @@ -0,0 +1,2 @@ +google-adk>=1.5.0 +pydantic>=2.0.0 \ No newline at end of file