feat(whatsapp): Add structured response base model for WhatsApp bot

- Create WhatsAppResponseBase model to standardize bot response structure
- Enhance WhatsAppBot to support generic structured output schemas
- Update _send_response method to handle structured response parsing
- Add type hints and documentation for new response handling mechanism
- Improve logging for structured response processing
- Enable more flexible and type-safe bot response generation
This change introduces a base model for WhatsApp bot responses that ensures a consistent response structure while allowing for extensible, type-safe output schemas.

Author: arthurbrenno

agentle/agents/whatsapp/models/whatsapp_response_base.py

@@ -0,0 +1,31 @@
+# Em: agentle/agents/whatsapp/models/whatsapp_response_base.py
+
+from rsb.models.base_model import BaseModel
+from rsb.models.field import Field
+
+
+class WhatsAppResponseBase(BaseModel):
+    """
+        Base class for WhatsApp bot structured responses.
+
+        This class ensures that all structured outputs from the WhatsApp bot
+        contain a 'response' field with the text to be sent to the user.
+
+        Developers can extend this class to add additional structured data
+        that they want to extract from the conversation.
+
+        Example:
+    ```python
+            class CustomerServiceResponse(WhatsAppResponseBase):
+                response: str  # Inherited - text to send to user
+                sentiment: Literal["happy", "neutral", "frustrated", "angry"]
+                urgency: int = Field(ge=1, le=5, description="Urgency level 1-5")
+                requires_human: bool = False
+                suggested_actions: list[str] = Field(default_factory=list)
+    ```
+    """
+
+    response: str = Field(
+        ...,
+        description="The text response that will be sent to the WhatsApp user. This field is required.",
+    )

agentle/agents/whatsapp/whatsapp_bot.py

@@ -33,6 +33,7 @@
 from agentle.agents.whatsapp.models.whatsapp_image_message import WhatsAppImageMessage
 from agentle.agents.whatsapp.models.whatsapp_media_message import WhatsAppMediaMessage
 from agentle.agents.whatsapp.models.whatsapp_message import WhatsAppMessage
+from agentle.agents.whatsapp.models.whatsapp_response_base import WhatsAppResponseBase
 from agentle.agents.whatsapp.models.whatsapp_session import WhatsAppSession
 from agentle.agents.whatsapp.models.whatsapp_text_message import WhatsAppTextMessage
 from agentle.agents.whatsapp.models.whatsapp_video_message import WhatsAppVideoMessage
@@ -128,14 +129,42 @@ class CallbackWithContext:
     context: dict[str, Any] = field(default_factory=dict)
 
 
-class WhatsAppBot(BaseModel):
+class WhatsAppBot[T_Schema: WhatsAppResponseBase = WhatsAppResponseBase](BaseModel):
     """
     WhatsApp bot that wraps an Agentle agent with enhanced message batching and spam protection.
 
-    Now uses the Agent's conversation store directly instead of managing contexts separately.
+    Now supports structured outputs through generic type parameter T_Schema.
+    The schema must extend WhatsAppResponseBase to ensure a 'response' field is always present.
+
+    Examples:
+    ```python
+        # Basic usage (no structured output)
+        agent = Agent(...)
+        bot = WhatsAppBot(agent=agent, provider=provider)
+
+        # With structured output
+        class MyResponse(WhatsAppResponseBase):
+            sentiment: Literal["happy", "sad", "neutral"]
+            urgency_level: int
+
+        agent = Agent[MyResponse](
+            response_schema=MyResponse,
+            instructions="Extract sentiment and urgency from the conversation..."
+        )
+        bot = WhatsAppBot[MyResponse](agent=agent, provider=provider)
+
+        # Access structured data in callbacks
+        async def my_callback(phone, chat_id, response, context):
+            if response and response.parsed:
+                print(f"Sentiment: {response.parsed.sentiment}")
+                print(f"Urgency: {response.parsed.urgency_level}")
+                # response.parsed.response is automatically sent to WhatsApp
+
+        bot.add_response_callback(my_callback)
+    ```
     """
 
-    agent: Agent[Any]
+    agent: Agent[T_Schema]
     provider: WhatsAppProvider
     tts_provider: TtsProvider | None = Field(default=None)
     file_storage_manager: FileStorageManager | None = Field(default=None)
@@ -1302,7 +1331,7 @@ async def _batch_processor(
 
     async def _process_message_batch(
         self, phone_number: PhoneNumber, session: WhatsAppSession, processing_token: str
-    ) -> GeneratedAssistantMessage[Any] | None:
+    ) -> GeneratedAssistantMessage[T_Schema] | None:
         """Process a batch of messages for a user with enhanced timeout protection.
 
         This method processes multiple messages that were received in quick succession
@@ -1504,7 +1533,7 @@ async def _process_single_message(
         message: WhatsAppMessage,
         session: WhatsAppSession,
         chat_id: ChatId | None = None,
-    ) -> GeneratedAssistantMessage[Any]:
+    ) -> GeneratedAssistantMessage[T_Schema]:
         """Process a single message immediately with quote message support."""
         logger.info(
             "[SINGLE_MESSAGE] ═══════════ SINGLE MESSAGE PROCESSING START ═══════════"
@@ -2207,7 +2236,7 @@ def _format_blockquote(self, line: str) -> str:
     async def _send_response(
         self,
         to: PhoneNumber,
-        response: GeneratedAssistantMessage[Any] | str,
+        response: GeneratedAssistantMessage[T_Schema] | str,
         reply_to: str | None = None,
     ) -> None:
         """Send response message(s) to user with enhanced error handling and retry logic.
@@ -2255,12 +2284,24 @@ async def _send_response(
             ...     reply_to="msg_123"
             ... )
         """
-        # Extract text from GeneratedAssistantMessage if needed
-        response_text = (
-            response.text
-            if isinstance(response, GeneratedAssistantMessage)
-            else response
-        )
+        response_text = ""
+        
+        if isinstance(response, GeneratedAssistantMessage):
+            # Check if we have structured output (parsed)
+            if response.parsed:
+                # Use the 'response' field from structured output
+                response_text = response.parsed.response
+                logger.debug(
+                    "[SEND_RESPONSE] Using structured output 'response' field "
+                    + f"(schema: {type(response.parsed).__name__})"
+                )
+            else:
+                # Fallback to text field
+                response_text = response.text
+                logger.debug("[SEND_RESPONSE] Using standard text response")
+        else:
+            # Direct string
+            response_text = response
 
         # Apply WhatsApp-specific markdown formatting
         response_text = self._format_whatsapp_markdown(response_text)