Python: Preserve Citation Title in AnnotationContent from Azure AI Foundry Annotations (#12152)

### Motivation and Context

When invoking an Azure AI Foundry agent via AzureAIAgent, url_citation
metadata such as the document filename (title) is omitted in the
resulting AnnotationContent. Only the url field is populated; the
filename (title) is lost, and no structured metadata is retained. This
breaks traceability and rich citation in downstream responses.

This PR updates the annotation mapping to include the title from
url_citation into the resulting AnnotationContent.

This PR also updates the content types to properly show the present
information either in the `to_dict()` call or `to_str` call, as well as
handling the attributes for the `from_element` class method.

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

### Description

Citations in responses returned via AzureAIAgent now retain the full
provenance information (url, title, etc.) as delivered by the underlying
agent, matching the behavior observed with direct AIProjectClient calls.
- Closes #12133 
- Adds further unit tests to validate functionality

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [X] The code builds clean without any errors or warnings
- [X] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [X] All unit tests pass, and I have added new tests where possible
- [X] I didn't break anyone 😄

Author: moonbox3

python/semantic_kernel/agents/azure_ai/agent_content_generation.py

@@ -28,7 +28,7 @@
     ThreadRun,
 )
 
-from semantic_kernel.contents.annotation_content import AnnotationContent
+from semantic_kernel.contents.annotation_content import AnnotationContent, CitationType
 from semantic_kernel.contents.chat_message_content import ChatMessageContent
 from semantic_kernel.contents.file_reference_content import FileReferenceContent
 from semantic_kernel.contents.function_call_content import FunctionCallContent
@@ -526,22 +526,30 @@ def generate_streaming_code_interpreter_content(
 def generate_annotation_content(
     annotation: MessageTextFilePathAnnotation | MessageTextFileCitationAnnotation | MessageTextUrlCitationAnnotation,
 ) -> AnnotationContent:
-    """Generate annotation content."""
+    """Generate annotation content with safe attribute access."""
     file_id = None
     url = None
-    if isinstance(annotation, MessageTextFilePathAnnotation) and annotation.file_path is not None:
+    title = None
+    citation_type = None
+    if isinstance(annotation, MessageTextFilePathAnnotation) and annotation.file_path:
         file_id = annotation.file_path.file_id
-    elif isinstance(annotation, MessageTextFileCitationAnnotation) and annotation.file_citation is not None:
+        citation_type = CitationType.FILE_PATH
+    elif isinstance(annotation, MessageTextFileCitationAnnotation) and annotation.file_citation:
         file_id = annotation.file_citation.file_id
-    elif isinstance(annotation, MessageTextUrlCitationAnnotation) and annotation.url_citation is not None:
-        url = annotation.url_citation.url if annotation.url_citation.url else None
+        citation_type = CitationType.FILE_CITATION
+    elif isinstance(annotation, MessageTextUrlCitationAnnotation) and annotation.url_citation:
+        url = annotation.url_citation.url
+        title = annotation.url_citation.title
+        citation_type = CitationType.URL_CITATION
 
     return AnnotationContent(
         file_id=file_id,
-        quote=annotation.text,
-        start_index=annotation.start_index if annotation.start_index is not None else None,
-        end_index=annotation.end_index if annotation.end_index is not None else None,
+        quote=getattr(annotation, "text", None),
+        start_index=getattr(annotation, "start_index", None),
+        end_index=getattr(annotation, "end_index", None),
         url=url,
+        title=title,
+        citation_type=citation_type,
     )
 
 
@@ -551,24 +559,31 @@ def generate_streaming_annotation_content(
     | MessageDeltaTextFileCitationAnnotation
     | MessageDeltaTextUrlCitationAnnotation,
 ) -> StreamingAnnotationContent:
-    """Generate streaming annotation content."""
+    """Generate streaming annotation content with defensive checks."""
     file_id = None
     url = None
     quote = None
+    title = None
+    citation_type = None
     if isinstance(annotation, MessageDeltaTextFilePathAnnotation) and annotation.file_path:
-        file_id = annotation.file_path.file_id if annotation.file_path.file_id else None
-        quote = annotation.text if annotation.text else None
+        file_id = annotation.file_path.file_id
+        quote = getattr(annotation, "text", None)
+        citation_type = CitationType.FILE_PATH
     elif isinstance(annotation, MessageDeltaTextFileCitationAnnotation) and annotation.file_citation:
-        file_id = annotation.file_citation.file_id if annotation.file_citation.file_id else None
-        quote = annotation.text if annotation.text else None
+        file_id = annotation.file_citation.file_id
+        quote = getattr(annotation, "text", None)
+        citation_type = CitationType.FILE_CITATION
     elif isinstance(annotation, MessageDeltaTextUrlCitationAnnotation) and annotation.url_citation:
-        url = annotation.url_citation.url if annotation.url_citation.url else None
-        quote = annotation.url_citation.title if annotation.url_citation.title else None
+        url = annotation.url_citation.url
+        title = annotation.url_citation.title
+        citation_type = CitationType.URL_CITATION
 
     return StreamingAnnotationContent(
         file_id=file_id,
         quote=quote,
-        start_index=annotation.start_index if annotation.start_index is not None else None,
-        end_index=annotation.end_index if annotation.end_index is not None else None,
+        start_index=getattr(annotation, "start_index", None),
+        end_index=getattr(annotation, "end_index", None),
         url=url,
+        title=title,
+        citation_type=citation_type,
     )

python/semantic_kernel/contents/annotation_content.py

@@ -5,8 +5,7 @@
 from typing import Any, ClassVar, Literal, TypeVar
 from xml.etree.ElementTree import Element  # nosec
 
-from pydantic import Field
-from pydantic_settings import SettingsConfigDict
+from pydantic import ConfigDict, Field
 
 from semantic_kernel.contents.const import ANNOTATION_CONTENT_TAG, ContentTypes
 from semantic_kernel.contents.kernel_content import KernelContent
@@ -17,12 +16,13 @@
 _T = TypeVar("_T", bound="AnnotationContent")
 
 
+@experimental
 class CitationType(str, Enum):
     """Citation type."""
 
     URL_CITATION = "url_citation"
+    FILE_PATH = "file_path"
     FILE_CITATION = "file_citation"
-    TEXT_CITATION = "text_citation"
 
 
 @experimental
@@ -39,19 +39,21 @@ class AnnotationContent(KernelContent):
     title: str | None = None
     citation_type: CitationType | None = Field(None, alias="type")
 
-    model_config = SettingsConfigDict(
+    model_config = ConfigDict(
         extra="ignore",
-        case_sensitive=False,
         populate_by_name=True,
     )
 
     def __str__(self) -> str:
         """Return the string representation of the annotation content."""
-        return f"AnnotationContent(file_id={self.file_id}, url={self.url}, quote={self.quote}, start_index={self.start_index}, end_index={self.end_index})"  # noqa: E501
+        ctype = self.citation_type.value if self.citation_type else None
+        return f"AnnotationContent(type={ctype}, file_id={self.file_id}, url={self.url}, quote={self.quote}, start_index={self.start_index}, end_index={self.end_index})"  # noqa: E501
 
     def to_element(self) -> Element:
         """Convert the annotation content to an Element."""
         element = Element(self.tag)
+        if self.citation_type:
+            element.set("type", self.citation_type)
         if self.file_id:
             element.set("file_id", self.file_id)
         if self.quote:
@@ -62,22 +64,27 @@ def to_element(self) -> Element:
             element.set("end_index", str(self.end_index))
         if self.url is not None:
             element.set("url", self.url)
+        if self.title is not None:
+            element.set("title", self.title)
         return element
 
     @classmethod
     def from_element(cls: type[_T], element: Element) -> _T:
         """Create an instance from an Element."""
         return cls(
+            type=element.get("type"),
             file_id=element.get("file_id"),
             quote=element.get("quote"),
             start_index=int(element.get("start_index")) if element.get("start_index") else None,  # type: ignore
             end_index=int(element.get("end_index")) if element.get("end_index") else None,  # type: ignore
             url=element.get("url") if element.get("url") else None,  # type: ignore
+            title=element.get("title") if element.get("title") else None,  # type: ignore
         )
 
     def to_dict(self) -> dict[str, Any]:
         """Convert the instance to a dictionary."""
+        ctype = self.citation_type.value if self.citation_type else None
         return {
             "type": "text",
-            "text": f"{self.file_id or self.url} {self.quote} (Start Index={self.start_index}->End Index={self.end_index})",  # noqa: E501
+            "text": f"type={ctype}, {self.file_id or self.url} {self.quote} (Start Index={self.start_index}->End Index={self.end_index})",  # noqa: E501
         }

python/semantic_kernel/contents/streaming_annotation_content.py

@@ -4,8 +4,9 @@
 from typing import Any, ClassVar, Literal, TypeVar
 from xml.etree.ElementTree import Element  # nosec
 
-from pydantic import Field
+from pydantic import ConfigDict, Field
 
+from semantic_kernel.contents.annotation_content import CitationType
 from semantic_kernel.contents.const import STREAMING_ANNOTATION_CONTENT_TAG, ContentTypes
 from semantic_kernel.contents.kernel_content import KernelContent
 from semantic_kernel.utils.feature_stage_decorator import experimental
@@ -29,14 +30,24 @@ class StreamingAnnotationContent(KernelContent):
     start_index: int | None = None
     end_index: int | None = None
     url: str | None = None
+    title: str | None = None
+    citation_type: CitationType | None = Field(None, alias="type")
+
+    model_config = ConfigDict(
+        extra="ignore",
+        populate_by_name=True,
+    )
 
     def __str__(self) -> str:
         """Return the string representation of the annotation content."""
-        return f"StreamingAnnotationContent(file_id={self.file_id}, url={self.url}, quote={self.quote}, start_index={self.start_index}, end_index={self.end_index})"  # noqa: E501
+        ctype = self.citation_type.value if self.citation_type else None
+        return f"StreamingAnnotationContent(type={ctype}, file_id={self.file_id}, url={self.url}, quote={self.quote}, title={self.title}, start_index={self.start_index}, end_index={self.end_index})"  # noqa: E501
 
     def to_element(self) -> Element:
         """Convert the annotation content to an Element."""
         element = Element(self.tag)
+        if self.citation_type:
+            element.set("type", self.citation_type)
         if self.file_id:
             element.set("file_id", self.file_id)
         if self.quote:
@@ -47,22 +58,27 @@ def to_element(self) -> Element:
             element.set("end_index", str(self.end_index))
         if self.url is not None:
             element.set("url", self.url)
+        if self.title is not None:
+            element.set("title", self.title)
         return element
 
     @classmethod
     def from_element(cls: type[_T], element: Element) -> _T:
         """Create an instance from an Element."""
         return cls(
+            type=element.get("type"),
             file_id=element.get("file_id"),
             quote=element.get("quote"),
             start_index=int(element.get("start_index")) if element.get("start_index") else None,  # type: ignore
             end_index=int(element.get("end_index")) if element.get("end_index") else None,  # type: ignore
             url=element.get("url") if element.get("url") else None,  # type: ignore
+            title=element.get("title") if element.get("title") else None,  # type: ignore
         )
 
     def to_dict(self) -> dict[str, Any]:
         """Convert the instance to a dictionary."""
+        ctype = self.citation_type.value if self.citation_type else None
         return {
             "type": "text",
-            "text": f"{self.file_id or self.url} {self.quote} (Start Index={self.start_index}->End Index={self.end_index})",  # noqa: E501
+            "text": f"type={ctype}, {self.file_id or self.url}, quote={self.quote}, title={self.title} (Start Index={self.start_index}->End Index={self.end_index})",  # noqa: E501
         }