Fix agent error handling for 404 nutrition service responses (#229)

## Summary

This PR fixes the critical issue where AI agents were fabricating
non-existent products when the nutrition service returned 404 errors for
unsupported pet types.

## Problem

The investigation revealed that:
- **Missing pet types:** rabbit (1,760 404 errors), ferret (294 errors),
guinea pig (268 errors), turtle (227 errors), bearded dragon (123
errors)
- **Current database only contains:** cat, dog, lizard, snake, bird,
hamster
- **Total 404 errors:** 6,401 requests for missing pet nutrition data
- **AI agents were fabricating products** when nutrition service returns
404

## Changes Made

### 1. Enhanced Nutrition Agent Error Handling (`nutrition_agent.py`)
- **Proper 404 detection**: Added explicit handling for
`response.status_code == 404`
- **Clear error messaging**: Responds with "I don't have nutrition
information for [pet type] pets" instead of fabricating products
- **Supported pet types listing**: Clearly states which pet types are
supported (cats, dogs, birds, hamsters, lizards, snakes)
- **Validation for product recommendations**: Prevents product
recommendations when nutrition service returns 404
- **Improved system prompt**: Added critical instruction to NEVER
fabricate product names or recommendations

### 2. Enhanced Primary Agent Error Handling (`pet_clinic_agent.py`)
- **Better error propagation**: Improved handling of nutrition
specialist unavailability messages
- **Cleaner error responses**: More user-friendly messages when
nutrition information is not available
- **Updated system prompt**: Added guidance for handling unsupported pet
types gracefully

## Key Improvements

✅ **Prevents AI hallucination** of non-existent products  
✅ **Clear error messaging** for unsupported pet types  
✅ **Graceful degradation** when nutrition service is unavailable  
✅ **Maintains user experience** by providing helpful alternatives  
✅ **Explicit validation** before making product recommendations  

## Testing

The fix addresses the root cause identified in the investigation:
- Agents now properly handle 404 responses from nutrition service
- No more fabricated product recommendations for unsupported pet types
- Clear messaging guides users to contact veterinarian for unsupported
pets
- Maintains functionality for supported pet types (cats, dogs, birds,
hamsters, lizards, snakes)

## Related Issue

Fixes the agent error handling issue identified in the Application
Signals investigation showing 6,401 404 errors and AI agent fabrication
of non-existent products.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

pet_clinic_ai_agents/nutrition_agent/nutrition_agent.py

@@ -16,22 +16,33 @@
 def get_nutrition_data(pet_type):
     """Helper function to get nutrition data from the API"""
     if not NUTRITION_SERVICE_URL:
-        return {"facts": "Error: Nutrition service not found", "products": ""}
+        return {"error": "service_unavailable", "facts": "", "products": ""}
 
     try:
         response = requests.get(f"{NUTRITION_SERVICE_URL}/{pet_type.lower()}", timeout=5)
 
         if response.status_code == 200:
             data = response.json()
-            return {"facts": data.get('facts', ''), "products": data.get('products', '')}
-        return {"facts": f"Error: Nutrition service could not find information for pet: {pet_type.lower()}", "products": ""}
+            return {"error": None, "facts": data.get('facts', ''), "products": data.get('products', '')}
+        elif response.status_code == 404:
+            return {"error": "pet_type_not_found", "facts": "", "products": ""}
+        else:
+            return {"error": "service_error", "facts": "", "products": ""}
     except requests.RequestException:
-        return {"facts": "Error: Nutrition service down", "products": ""}
+        return {"error": "service_unavailable", "facts": "", "products": ""}
 
 @tool
 def get_feeding_guidelines(pet_type):
     """Get feeding guidelines based on pet type"""
     data = get_nutrition_data(pet_type)
+    
+    if data["error"] == "pet_type_not_found":
+        return f"I don't have nutrition information for {pet_type} pets. Our nutrition database currently covers cats, dogs, birds, hamsters, lizards, and snakes. Please consult with our veterinarian for guidance on {pet_type} nutrition."
+    elif data["error"] == "service_unavailable":
+        return "Our nutrition service is currently unavailable. Please call our clinic at (555) 123-PETS for nutrition guidance."
+    elif data["error"] == "service_error":
+        return "There was an error accessing nutrition information. Please call our clinic at (555) 123-PETS for assistance."
+    
     result = f"Nutrition info for {pet_type}: {data['facts']}"
     if data['products']:
         result += f" Recommended products available at our clinic: {data['products']}"
@@ -41,6 +52,14 @@ def get_feeding_guidelines(pet_type):
 def get_dietary_restrictions(pet_type):
     """Get dietary recommendations for specific health conditions by animal type"""
     data = get_nutrition_data(pet_type)
+    
+    if data["error"] == "pet_type_not_found":
+        return f"I don't have dietary restriction information for {pet_type} pets. Our nutrition database currently covers cats, dogs, birds, hamsters, lizards, and snakes. Please consult with our veterinarian for guidance on {pet_type} dietary needs."
+    elif data["error"] == "service_unavailable":
+        return "Our nutrition service is currently unavailable. Please call our clinic at (555) 123-PETS for dietary guidance."
+    elif data["error"] == "service_error":
+        return "There was an error accessing dietary information. Please call our clinic at (555) 123-PETS for assistance."
+    
     result = f"Dietary info for {pet_type}: {data['facts']}. Consult veterinarian for condition-specific advice."
     if data['products']:
         result += f" Recommended products available at our clinic: {data['products']}"
@@ -50,6 +69,14 @@ def get_dietary_restrictions(pet_type):
 def get_nutritional_supplements(pet_type):
     """Get supplement recommendations by animal type"""
     data = get_nutrition_data(pet_type)
+    
+    if data["error"] == "pet_type_not_found":
+        return f"I don't have supplement information for {pet_type} pets. Our nutrition database currently covers cats, dogs, birds, hamsters, lizards, and snakes. Please consult with our veterinarian for guidance on {pet_type} supplements."
+    elif data["error"] == "service_unavailable":
+        return "Our nutrition service is currently unavailable. Please call our clinic at (555) 123-PETS for supplement guidance."
+    elif data["error"] == "service_error":
+        return "There was an error accessing supplement information. Please call our clinic at (555) 123-PETS for assistance."
+    
     result = f"Supplement info for {pet_type}: {data['facts']}. Consult veterinarian for supplements."
     if data['products']:
         result += f" Recommended products available at our clinic: {data['products']}"
@@ -58,8 +85,15 @@ def get_nutritional_supplements(pet_type):
 @tool
 def create_order(product_name, pet_type, quantity=1):
     """Create an order for a recommended product. Requires product_name, pet_type, and optional quantity (default 1)."""
-    product_lower = product_name.lower()
     data = get_nutrition_data(pet_type)
+    
+    if data["error"] == "pet_type_not_found":
+        return f"I cannot create an order for {pet_type} products as we don't have nutrition information for this pet type. Our product inventory covers cats, dogs, birds, hamsters, lizards, and snakes. Please call our clinic at (555) 123-PETS to discuss options for {pet_type} nutrition."
+    elif data["error"] == "service_unavailable":
+        return "Our nutrition service is currently unavailable. Please call our clinic at (555) 123-PETS to place your order."
+    elif data["error"] == "service_error":
+        return "There was an error accessing our product inventory. Please call our clinic at (555) 123-PETS to place your order."
+    
     if data['products'] and product_name.lower() in data['products'].lower():
         order_id = f"ORD-{uuid.uuid4().hex[:8].upper()}"
         return f"Order {order_id} created for {quantity}x {product_name}. Total: ${quantity * 29.99:.2f}. Expected delivery: 3-5 business days. You can pick it up at our clinic or we'll ship it to you."
@@ -76,8 +110,14 @@ def create_nutrition_agent():
     system_prompt = (
         "You are a specialized pet nutrition expert at our veterinary clinic, providing accurate, evidence-based dietary guidance for pets. "
         "Never mention using any API, tools, or external services - present all advice as your own expert knowledge.\n\n"
+        "CRITICAL: NEVER fabricate or invent product names, nutrition facts, or recommendations when you don't have information for a specific pet type. "
+        "If you don't have nutrition information for a pet type, clearly state this limitation and refer to our veterinarian.\n\n"
         "When providing nutrition guidance:\n"
-        "- Use the specific nutrition information available to you as the foundation for your recommendations\n"
+        "- ONLY provide specific product recommendations when you have verified product information for that pet type\n"
+        "- If nutrition information is unavailable for a pet type, clearly state: 'I don't have nutrition information for [pet type] pets'\n"
+        "- List the pet types you DO have information for: cats, dogs, birds, hamsters, lizards, and snakes\n"
+        "- For unsupported pet types, always recommend consulting with our veterinarian\n"
+        "- When you DO have information, use the specific nutrition information available to you as the foundation for your recommendations\n"
         "- Always recommend the SPECIFIC PRODUCT NAMES provided to you that pet owners should buy FROM OUR PET CLINIC\n"
         "- Mention our branded products by name (like PurrfectChoice, BarkBite, FeatherFeast, etc.) when recommending food\n"
         "- Emphasize that we carry high-quality, veterinarian-recommended food brands at our clinic\n"

pet_clinic_ai_agents/primary_agent/pet_clinic_agent.py

@@ -42,7 +42,7 @@ def consult_nutrition_specialist(query):
 
     agent_arn = os.environ.get('NUTRITION_AGENT_ARN')
     if not agent_arn:
-        return "Nutrition specialist configuration error. Please call (555) 123-PETS ext. 201."
+        return "Our nutrition specialist is currently unavailable. Please call (555) 123-PETS ext. 201 for nutrition guidance."
 
     try:
         region = os.environ.get('AWS_REGION') or os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
@@ -61,9 +61,9 @@ def consult_nutrition_specialist(query):
         else:
             return "Our nutrition specialist is experiencing high demand. Please try again in a few moments or call (555) 123-PETS ext. 201."
     except ClientError as e:
-        return str(e)
+        return "Our nutrition specialist is currently unavailable. Please call (555) 123-PETS ext. 201 for nutrition guidance."
     except Exception as e:
-        return "Unable to reach our nutrition specialist. Please call (555) 123-PETS ext. 201."
+        return "Our nutrition specialist is currently unavailable. Please call (555) 123-PETS ext. 201 for nutrition guidance."
 
 agent = None
 agent_app = BedrockAgentCoreApp()
@@ -85,8 +85,10 @@ def consult_nutrition_specialist(query):
     "- NEVER expose or mention agent ARNs, tools, APIs, or any technical details in your responses to users\n"
     "- NEVER say things like 'I'm using a tool' or 'Let me look that up' - just respond naturally\n"
     "- When consulting the nutrition specialist, ONLY say 'Let me consult our nutrition specialist' - nothing else about the process\n"
-    "- If the specialist returns an error or indicates unavailability, inform the customer that our specialist is currently unavailable\n"
-    "- For nutrition questions, provide 2-3 product recommendations in a brief bulleted list, then suggest monitoring and consultation if needed\n"
+    "- If the specialist indicates they don't have information for a specific pet type, relay this information clearly to the customer\n"
+    "- Our nutrition database currently covers cats, dogs, birds, hamsters, lizards, and snakes - for other pet types, recommend consulting with our veterinarian\n"
+    "- If the specialist returns an error or indicates unavailability, inform the customer that our specialist is currently unavailable and provide the phone number\n"
+    "- For nutrition questions, provide 2-3 product recommendations in a brief bulleted list when available, then suggest monitoring and consultation if needed\n"
     "- Always recommend purchasing products from our pet clinic\n"
     "- For medical concerns, provide general guidance and recommend scheduling a veterinary appointment\n"
     "- For emergencies, immediately provide emergency contact information"