Merge branch 'main' into main

Author: pontemonti

docs/prd/azure-ai-foundry-chat-history-api-tasks.md

@@ -11,18 +11,21 @@
 
 # Standard library imports
 import logging
-from typing import Optional, List, Tuple
+from typing import List, Optional, Sequence, Tuple
 
 # Third-party imports - Azure AI
+from azure.ai.agents import AgentsClient
+from azure.ai.agents.models import McpTool, ThreadMessage, ToolResources
 from azure.ai.projects import AIProjectClient
 from azure.identity import DefaultAzureCredential
-from azure.ai.agents.models import McpTool, ToolResources
 from microsoft_agents.hosting.core import Authorization, TurnContext
+
+from microsoft_agents_a365.runtime import OperationError, OperationResult
 from microsoft_agents_a365.runtime.utility import Utility
+from microsoft_agents_a365.tooling.models import ChatHistoryMessage, ToolOptions
 from microsoft_agents_a365.tooling.services.mcp_tool_server_configuration_service import (
     McpToolServerConfigurationService,
 )
-from microsoft_agents_a365.tooling.models import ToolOptions
 from microsoft_agents_a365.tooling.utils.constants import Constants
 from microsoft_agents_a365.tooling.utils.utility import get_mcp_platform_authentication_scope
 
@@ -217,3 +220,253 @@ async def _get_mcp_tool_definitions_and_resources(
         )
 
         return (tool_definitions, combined_tool_resources)
+
+    # ============================================================================
+    # Public Methods - Chat History API
+    # ============================================================================
+
+    async def send_chat_history_messages(
+        self,
+        turn_context: TurnContext,
+        messages: Sequence[ThreadMessage],
+        tool_options: Optional[ToolOptions] = None,
+    ) -> OperationResult:
+        """
+        Send Azure AI Foundry chat history messages to the MCP platform.
+
+        This method accepts a sequence of Azure AI Foundry ThreadMessage objects,
+        converts them to ChatHistoryMessage format, and sends them to the MCP
+        platform for real-time threat protection.
+
+        Args:
+            turn_context: TurnContext from the Agents SDK containing conversation info.
+            messages: Sequence of Azure AI Foundry ThreadMessage objects to send.
+            tool_options: Optional configuration for the request.
+
+        Returns:
+            OperationResult indicating success or failure.
+
+        Raises:
+            ValueError: If turn_context or messages is None.
+
+        Example:
+            >>> service = McpToolRegistrationService()
+            >>> messages = await agents_client.messages.list(thread_id=thread_id)
+            >>> result = await service.send_chat_history_messages(
+            ...     turn_context, list(messages)
+            ... )
+            >>> if result.succeeded:
+            ...     print("Chat history sent successfully")
+        """
+        # Input validation
+        if turn_context is None:
+            raise ValueError("turn_context cannot be None")
+        if messages is None:
+            raise ValueError("messages cannot be None")
+
+        self._logger.info(f"Sending {len(messages)} Azure AI Foundry messages as chat history")
+
+        # Set default options with orchestrator name
+        if tool_options is None:
+            tool_options = ToolOptions(orchestrator_name=self._orchestrator_name)
+        elif tool_options.orchestrator_name is None:
+            tool_options.orchestrator_name = self._orchestrator_name
+
+        try:
+            # Convert ThreadMessage objects to ChatHistoryMessage format
+            chat_history_messages = self._convert_thread_messages_to_chat_history(messages)
+
+            self._logger.debug(
+                f"Converted {len(chat_history_messages)} messages to ChatHistoryMessage format"
+            )
+
+            # Delegate to core service
+            result = await self._mcp_server_configuration_service.send_chat_history(
+                turn_context=turn_context,
+                chat_history_messages=chat_history_messages,
+                options=tool_options,
+            )
+
+            if result.succeeded:
+                self._logger.info(
+                    f"Chat history sent successfully with {len(chat_history_messages)} messages"
+                )
+            else:
+                self._logger.error(f"Failed to send chat history: {result}")
+
+            return result
+
+        except ValueError:
+            # Re-raise validation errors from the core service
+            raise
+        except Exception as ex:
+            self._logger.error(f"Failed to send chat history messages: {ex}")
+            return OperationResult.failed(OperationError(ex))
+
+    async def send_chat_history(
+        self,
+        agents_client: AgentsClient,
+        thread_id: str,
+        turn_context: TurnContext,
+        tool_options: Optional[ToolOptions] = None,
+    ) -> OperationResult:
+        """
+        Retrieve and send chat history from Azure AI Foundry to the MCP platform.
+
+        This method retrieves messages from the Azure AI Foundry Agents API using
+        the provided client and thread ID, converts them to ChatHistoryMessage
+        format, and sends them to the MCP platform.
+
+        Args:
+            agents_client: The Azure AI Foundry AgentsClient instance.
+            thread_id: The thread ID containing the messages to send.
+            turn_context: TurnContext from the Agents SDK containing conversation info.
+            tool_options: Optional configuration for the request.
+
+        Returns:
+            OperationResult indicating success or failure.
+
+        Raises:
+            ValueError: If agents_client, thread_id, or turn_context is None/empty.
+
+        Example:
+            >>> from azure.ai.agents import AgentsClient
+            >>> from azure.identity import DefaultAzureCredential
+            >>>
+            >>> client = AgentsClient(endpoint, credential=DefaultAzureCredential())
+            >>> service = McpToolRegistrationService()
+            >>> result = await service.send_chat_history(
+            ...     client, thread_id, turn_context
+            ... )
+        """
+        # Input validation
+        if agents_client is None:
+            raise ValueError("agents_client cannot be None")
+        if thread_id is None or not thread_id.strip():
+            raise ValueError("thread_id cannot be empty")
+        if turn_context is None:
+            raise ValueError("turn_context cannot be None")
+
+        try:
+            # Retrieve messages from the thread
+            messages: List[ThreadMessage] = []
+            async for message in agents_client.messages.list(thread_id=thread_id):
+                messages.append(message)
+
+            self._logger.info(f"Retrieved {len(messages)} messages from thread {thread_id}")
+
+            # Delegate to send_chat_history_messages
+            return await self.send_chat_history_messages(
+                turn_context=turn_context,
+                messages=messages,
+                tool_options=tool_options,
+            )
+
+        except ValueError:
+            # Re-raise validation errors
+            raise
+        except Exception as ex:
+            self._logger.error(f"Failed to send chat history from thread {thread_id}: {ex}")
+            return OperationResult.failed(OperationError(ex))
+
+    # ============================================================================
+    # Private Methods - Message Conversion Helpers
+    # ============================================================================
+
+    def _convert_thread_messages_to_chat_history(
+        self,
+        messages: Sequence[ThreadMessage],
+    ) -> List[ChatHistoryMessage]:
+        """
+        Convert Azure AI Foundry ThreadMessage objects to ChatHistoryMessage format.
+
+        This internal helper method transforms Azure AI Foundry's native ThreadMessage
+        objects into the ChatHistoryMessage format expected by the MCP platform's
+        real-time threat protection endpoint.
+
+        Args:
+            messages: Sequence of ThreadMessage objects to convert.
+
+        Returns:
+            List of ChatHistoryMessage objects ready for the MCP platform.
+
+        Note:
+            - Messages with None id, None role, or empty content are filtered out
+            - Role is extracted via the .value property of the MessageRole enum
+            - Timestamp is taken from message.created_at
+        """
+        history_messages: List[ChatHistoryMessage] = []
+
+        for message in messages:
+            # Skip None messages
+            if message is None:
+                self._logger.warning("Skipping null message")
+                continue
+
+            # Skip messages with None id
+            if message.id is None:
+                self._logger.warning("Skipping message with null ID")
+                continue
+
+            # Skip messages with None role
+            if message.role is None:
+                self._logger.warning(f"Skipping message with null role (ID: {message.id})")
+                continue
+
+            # Extract content from message
+            content = self._extract_content_from_message(message)
+
+            # Skip messages with empty content
+            if not content or not content.strip():
+                self._logger.warning(f"Skipping message {message.id} with empty content")
+                continue
+
+            # Convert role enum to lowercase string
+            role_value = message.role.value if hasattr(message.role, "value") else str(message.role)
+            role = role_value.lower()
+
+            # Create ChatHistoryMessage
+            history_message = ChatHistoryMessage(
+                id=message.id,
+                role=role,
+                content=content,
+                timestamp=message.created_at,
+            )
+            history_messages.append(history_message)
+
+            self._logger.debug(
+                f"Converted message {message.id} with role '{role}' to ChatHistoryMessage"
+            )
+
+        if len(history_messages) == 0 and len(messages) > 0:
+            self._logger.warning("All messages were filtered out during conversion")
+
+        return history_messages
+
+    def _extract_content_from_message(self, message: ThreadMessage) -> str:
+        """
+        Extract text content from a ThreadMessage's content items.
+
+        This method iterates through the message's content list and extracts
+        text from MessageTextContent items, concatenating them with spaces.
+
+        Args:
+            message: Azure AI Foundry ThreadMessage object.
+
+        Returns:
+            Concatenated text content as string, or empty string if no text found.
+        """
+        if message.content is None or len(message.content) == 0:
+            return ""
+
+        text_parts: List[str] = []
+
+        for content_item in message.content:
+            # Check for MessageTextContent by duck typing (has text attribute with value)
+            # This handles both real SDK types and mock objects in tests
+            if hasattr(content_item, "text") and content_item.text is not None:
+                text_value = getattr(content_item.text, "value", None)
+                if text_value is not None and text_value:
+                    text_parts.append(text_value)
+
+        return " ".join(text_parts)

docs/prd/azure-ai-foundry-chat-history-api.md

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.

libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/microsoft_agents_a365/tooling/extensions/azureaifoundry/services/mcp_tool_registration_service.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.