Changes for beta 8 release of Python Azure AI Projects SDK (#39990)

Author: dargilco

Diff for: .vscode/cspell.json

@@ -36,6 +36,7 @@
     "sdk/ai/azure-ai-inference/samples/hello_how_are_you.mp3",
     "sdk/ai/azure-ai-inference/tests/hello_how_are_you.mp3",
     "sdk/ai/azure-ai-projects/samples/agents/nifty_500_quarterly_results.csv",
+    "sdk/ai/azure-ai-projects/samples/agents/tripadvisor_openapi.json",
     "/sdk/ai/azure-ai-projects/samples/evaluations/async_samples/data/**",
     "/sdk/ai/azure-ai-projects/samples/evaluations/data/**",
     "sdk/ai/azure-ai-resources/azure/ai/resources/_index/_langchain/vendor/**",
@@ -1344,6 +1345,10 @@
     {
       "filename": "sdk/ai/azure-ai-projects/**",
       "words": [
+        "coso",
+        "longtitude",
+        "abbrev",
+        "accommodations",
         "ENTRAID",
         "entraid",
         "aiservices",

Diff for: sdk/ai/azure-ai-projects/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Release History
 
+## 1.0.0b8 (2025-03-28)
+
+### Features added
+
+* New parameters added for Azure AI Search tool, with corresponding sample update.
+* Fabric tool REST name updated, along with convenience code.
+
+### Sample updates
+
+* Sample update demonstrating new parameters added for Azure AI Search tool.
+* Sample added using OpenAPI tool against authenticated TripAdvisor API spec.
+
+### Bugs Fixed
+
+* Fix for a bug in Agent tracing causing event handler return values to not be returned when tracing is enabled.
+* Fix for a bug in Agent tracing causing tool calls not to be recorded in traces.
+* Fix for a bug in Agent tracing causing function tool calls to not work properly when tracing is enabled.
+* Fix for a bug in Agent streaming, where `agent_id` was not included in the response. This caused the SDK not to make function calls when the thread run status is `requires_action`.
+
 ## 1.0.0b7 (2025-03-06)
 
 ### Features added

Diff for: sdk/ai/azure-ai-projects/README.md

@@ -46,6 +46,7 @@ To report an issue with the client library, or request additional features, plea
       - [Function call](#create-agent-with-function-call)
       - [Azure Function Call](#create-agent-with-azure-function-call)
       - [OpenAPI](#create-agent-with-openapi)
+      - [Fabric data](#create-an-agent-with-fabric)
     - [Create thread](#create-thread) with
       - [Tool resource](#create-thread-with-tool-resource)
     - [Create message](#create-message) with:
@@ -455,17 +456,19 @@ Here is an example to integrate Azure AI Search:
 <!-- SNIPPET:sample_agents_azure_ai_search.create_agent_with_azure_ai_search_tool -->
 
 ```python
-conn_list = project_client.connections.list()
-conn_id = ""
-for conn in conn_list:
-    if conn.connection_type == ConnectionType.AZURE_AI_SEARCH:
-        conn_id = conn.id
-        break
+connection = project_client.connections.get(connection_name=os.environ["AI_SEARCH_CONNECTION_NAME"])
+conn_id = connection.id
 
 print(conn_id)
 
 # Initialize agent AI search tool and add the search index connection id
-ai_search = AzureAISearchTool(index_connection_id=conn_id, index_name="myindexname")
+ai_search = AzureAISearchTool(
+    index_connection_id=conn_id,
+    index_name="sample_index",
+    query_type=AzureAISearchQueryType.SIMPLE,
+    top_k=3,
+    filter=""
+)
 
 # Create agent with AI search tool and process assistant run
 with project_client:
@@ -480,6 +483,34 @@ with project_client:
 
 <!-- END SNIPPET -->
 
+If the agent has found the relevant information in the index, the reference
+and annotation will be provided in the message response. In the example above, we replace
+the reference placeholder by the actual reference and url. Please note, that to
+get sensible result, the index needs to have fields "title" and "url".
+
+<!-- SNIPPET:sample_agents_azure_ai_search.populate_references_agent_with_azure_ai_search_tool -->
+
+```python
+# Fetch and log all messages
+messages = project_client.agents.list_messages(thread_id=thread.id, order=ListSortOrder.ASCENDING)
+for message in messages.data:
+    if message.role == MessageRole.AGENT and message.url_citation_annotations:
+        placeholder_annotations = {
+            annotation.text: f" [see {annotation.url_citation.title}] ({annotation.url_citation.url})"
+            for annotation in message.url_citation_annotations
+        }
+        for message_text in message.text_messages:
+            message_str = message_text.text.value
+            for k, v in placeholder_annotations.items():
+                message_str = message_str.replace(k, v)
+            print(f"{message.role}: {message_str}")
+    else:
+        for message_text in message.text_messages:
+            print(f"{message.role}: {message_text.text.value}")
+```
+
+<!-- END SNIPPET -->
+
 #### Create Agent with Function Call
 
 You can enhance your Agents by defining callback functions as function tools. These can be provided to `create_agent` via either the `toolset` parameter or the combination of `tools` and `tool_resources`. Here are the distinctions:
@@ -780,6 +811,37 @@ with project_client:
 
 <!-- END SNIPPET -->
 
+#### Create an Agent with Fabric
+
+To enable your Agent to answer queries using Fabric data, use `FabricTool` along with a connection to the Fabric resource.
+
+Here is an example:
+
+<!-- SNIPPET:sample_agents_fabric.create_agent_with_fabric_tool -->
+
+```python
+fabric_connection = project_client.connections.get(connection_name=os.environ["FABRIC_CONNECTION_NAME"])
+conn_id = fabric_connection.id
+
+print(conn_id)
+
+# Initialize an Agent Fabric tool and add the connection id
+fabric = FabricTool(connection_id=conn_id)
+
+# Create an Agent with the Fabric tool and process an Agent run
+with project_client:
+    agent = project_client.agents.create_agent(
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        name="my-agent",
+        instructions="You are a helpful agent",
+        tools=fabric.definitions,
+        headers={"x-ms-enable-preview": "true"},
+    )
+```
+
+<!-- END SNIPPET -->
+
+
 #### Create Thread
 
 For each session or conversation, a thread is required.   Here is an example:

Diff for: sdk/ai/azure-ai-projects/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/ai/azure-ai-projects",
-  "Tag": "python/ai/azure-ai-projects_e7dc31a23f"
+  "Tag": "python/ai/azure-ai-projects_819c7192e3"
 }

Diff for: sdk/ai/azure-ai-projects/azure/ai/projects/_serialization.py

@@ -411,7 +411,7 @@ def from_dict(
         :param function key_extractors: A key extractor function.
         :param str content_type: JSON by default, set application/xml if XML.
         :returns: An instance of this model
-        :raises: DeserializationError if something went wrong
+        :raises DeserializationError: if something went wrong
         :rtype: Self
         """
         deserializer = Deserializer(cls._infer_class_models())

Diff for: sdk/ai/azure-ai-projects/azure/ai/projects/_version.py

@@ -6,4 +6,4 @@
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
 
-VERSION = "1.0.0b7"
+VERSION = "1.0.0b8"

Diff for: sdk/ai/azure-ai-projects/azure/ai/projects/aio/operations/_operations.py

@@ -5144,8 +5144,8 @@ async def _list_connections(
         """List the details of all the connections (not including their credentials).
 
         :keyword category: Category of the workspace connection. Known values are: "AzureOpenAI",
-         "Serverless", "AzureBlob", "AIServices", "CognitiveSearch", and "API Key". Default value is
-         None.
+         "Serverless", "AzureBlob", "AIServices", "CognitiveSearch", "ApiKey", "CustomKeys", and
+         "CognitiveService". Default value is None.
         :paramtype category: str or ~azure.ai.projects.models.ConnectionType
         :keyword include_all: Indicates whether to list datastores. Service default: do not list
          datastores. Default value is None.

Diff for: sdk/ai/azure-ai-projects/azure/ai/projects/models/__init__.py

@@ -14,6 +14,8 @@
 
 
 from ._models import (  # type: ignore
+    AISearchIndexResource,
+    AOAIModelConfig,
     Agent,
     AgentDeletionStatus,
     AgentThread,
@@ -34,6 +36,7 @@
     Dataset,
     Evaluation,
     EvaluationSchedule,
+    EvaluationTarget,
     EvaluatorConfiguration,
     FileDeletionStatus,
     FileListResponse,
@@ -46,8 +49,8 @@
     FunctionName,
     FunctionToolDefinition,
     IncompleteRunDetails,
-    IndexResource,
     InputData,
+    MAASModelConfig,
     MessageAttachment,
     MessageContent,
     MessageDelta,
@@ -145,6 +148,7 @@
     SubmitToolOutputsAction,
     SubmitToolOutputsDetails,
     SystemData,
+    TargetModelConfig,
     ThreadDeletionStatus,
     ThreadMessage,
     ThreadMessageOptions,
@@ -185,6 +189,7 @@
     AgentsApiToolChoiceOptionMode,
     AgentsNamedToolChoiceType,
     AuthenticationType,
+    AzureAISearchQueryType,
     ConnectionType,
     DoneEvent,
     ErrorEvent,
@@ -224,6 +229,8 @@
 from ._patch import patch_sdk as _patch_sdk
 
 __all__ = [
+    "AISearchIndexResource",
+    "AOAIModelConfig",
     "Agent",
     "AgentDeletionStatus",
     "AgentThread",
@@ -244,6 +251,7 @@
     "Dataset",
     "Evaluation",
     "EvaluationSchedule",
+    "EvaluationTarget",
     "EvaluatorConfiguration",
     "FileDeletionStatus",
     "FileListResponse",
@@ -256,8 +264,8 @@
     "FunctionName",
     "FunctionToolDefinition",
     "IncompleteRunDetails",
-    "IndexResource",
     "InputData",
+    "MAASModelConfig",
     "MessageAttachment",
     "MessageContent",
     "MessageDelta",
@@ -355,6 +363,7 @@
     "SubmitToolOutputsAction",
     "SubmitToolOutputsDetails",
     "SystemData",
+    "TargetModelConfig",
     "ThreadDeletionStatus",
     "ThreadMessage",
     "ThreadMessageOptions",
@@ -392,6 +401,7 @@
     "AgentsApiToolChoiceOptionMode",
     "AgentsNamedToolChoiceType",
     "AuthenticationType",
+    "AzureAISearchQueryType",
     "ConnectionType",
     "DoneEvent",
     "ErrorEvent",

Diff for: sdk/ai/azure-ai-projects/azure/ai/projects/models/_enums.py

@@ -39,8 +39,8 @@ class AgentsNamedToolChoiceType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Tool type ``file_search``"""
     BING_GROUNDING = "bing_grounding"
     """Tool type ``bing_grounding``"""
-    MICROSOFT_FABRIC = "fabric_aiskill"
-    """Tool type ``fabric_aiskill``"""
+    MICROSOFT_FABRIC = "fabric_dataagent"
+    """Tool type ``fabric_dataagent``"""
     SHAREPOINT = "sharepoint_grounding"
     """Tool type ``sharepoint_grounding``"""
     AZURE_AI_SEARCH = "azure_ai_search"
@@ -50,6 +50,8 @@ class AgentsNamedToolChoiceType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
 class AgentStreamEvent(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Each event in a server-sent events stream has an ``event`` and ``data`` property:
 
+
+
     .. code-block::
 
        event: thread.created
@@ -58,7 +60,7 @@ class AgentStreamEvent(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     We emit events whenever a new object is created, transitions to a new state, or is being
     streamed in parts (deltas). For example, we emit ``thread.run.created`` when a new run
     is created, ``thread.run.completed`` when a run completes, and so on. When an Agent chooses
-    to create a message during a run, we emit a ``thread.message.created event``\\ , a
+    to create a message during a run, we emit a ``thread.message.created event``, a
     ``thread.message.in_progress`` event, many ``thread.message.delta`` events, and finally a
     ``thread.message.completed`` event.
 
@@ -134,10 +136,27 @@ class AuthenticationType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Entra ID authentication (formerly known as AAD)"""
     SAS = "SAS"
     """Shared Access Signature (SAS) authentication"""
+    CUSTOM = "CustomKeys"
+    """Custom authentication"""
     NONE = "None"
     """No authentication"""
 
 
+class AzureAISearchQueryType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
+    """Available query types for Azure AI Search tool."""
+
+    SIMPLE = "simple"
+    """Query type ``simple``"""
+    SEMANTIC = "semantic"
+    """Query type ``semantic``"""
+    VECTOR = "vector"
+    """Query type ``vector``"""
+    VECTOR_SIMPLE_HYBRID = "vector_simple_hybrid"
+    """Query type ``vector_simple_hybrid``"""
+    VECTOR_SEMANTIC_HYBRID = "vector_semantic_hybrid"
+    """Query type ``vector_semantic_hybrid``"""
+
+
 class ConnectionType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """The Type (or category) of the connection."""
 
@@ -153,6 +172,10 @@ class ConnectionType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Azure AI Search"""
     API_KEY = "ApiKey"
     """Generic connection that uses API Key authentication"""
+    CUSTOM = "CustomKeys"
+    """Generic connection that uses Custom authentication"""
+    COGNITIVE_SERVICE = "CognitiveService"
+    """Cognitive Service"""
 
 
 class DoneEvent(str, Enum, metaclass=CaseInsensitiveEnumMeta):
@@ -301,7 +324,6 @@ class MessageStreamEvent(str, Enum, metaclass=CaseInsensitiveEnumMeta):
 class OpenApiAuthType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Authentication type for OpenApi endpoint. Allowed types are:
 
-
     * Anonymous (no authentication required)
     * Connection (requires connection_id to endpoint, as setup in AI Foundry)
     * Managed_Identity (requires audience for identity based auth).