Feature/azure ai agents/1.1.0b3 (#41829)

* Demonstrate the include parameter usage. (#41523)

* Demonstrate the include parameter usage

* Enable tests for reference text inclusion.

* Add file search with streaming samples (#41551)

* Small fix and use projects for getting connection ID (#41576)

* Update readme (#41527)

* Update readme

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* update

* Takes Jarno recommendation

---------

Co-authored-by: Copilot <[email protected]>

* Howie/next lint (#41621)

* Fix pylintrc to exclude agents generated code (#41612)

* Fix pylintrc to exclude agents generated code

* Update pylintrc

Co-authored-by: Copilot <[email protected]>

* Resolved

* Update eng/pylintrc

* Update pylintrc

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Libba Lawrence <[email protected]>

* Fix lint

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Libba Lawrence <[email protected]>

* Add support for Deep Research tool (#41696)

* Minor updates related to Deep Research tool & samples (#41783)

* Run black

* Remove outdated comment from samples per Jarno's advice

* Update chagne log to mention Deep Research tool

* fixing a tracing bug with paged lists (#41777)

* fixing a tracing bug with paged lists

* updating tests

* updating assests.json

* fixing code checker issues

* updating tests

* updating assets.json

* updating assests.json

* updating assests.json

* Improve doc for create agent and agentsclient init (#41821) (#41824)

* Improve doc for create agent and agentsclient init

* resolved comments

* resolved comments

* Deep Research update (#41823)

* update deep research samples

* add async sample

* update READEM

* update

* update samples

* pr feedback

* Update CHANGELOG.md

* Update CHANGELOG.md

* Update CHANGELOG.md

---------

Co-authored-by: Nikolay Rovinskiy <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Libba Lawrence <[email protected]>
Co-authored-by: Darren Cohen <[email protected]>
Co-authored-by: M-Hietala <[email protected]>
Co-authored-by: Jarno Hakulinen <[email protected]>

Author: 7 people

sdk/ai/azure-ai-agents/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 # Release History
 
+## 1.1.0b3 (2025-06-30)
+
+### Features Added
+
+- Added support for Deep Research tool. For more information, see https://aka.ms/agents-deep-research.
+
+### Bugs Fixed
+
+- Fixed a tracing related bug that caused an error when process was ending if messages or run steps were listed and the resulting list was not iterated completely.
+
+### Sample updates
+
+- The file search samples were updated to demonstrate retrieving text associated with citations.
+- Added samples for file search citation with streaming.
+- Added samples showing usage of Deep Research tool (sync and async).
+
 ## 1.1.0b2 (2025-06-09)
 
 ### Bugs Fixed
@@ -11,6 +27,7 @@
 - Fixed a tracing related bug that caused process_thread_run span to not appear when streaming is used without event handler.
 
 ### Sample updates
+
 - Changed all samples to use `AIProjectClient` which is recommended to specify endpoint and credential.
 - Added `sample_agents_stream_iteration_with_functions.py`
 

sdk/ai/azure-ai-agents/README.md

@@ -37,6 +37,7 @@ To report an issue with the client library, or request additional features, plea
     - [Azure Function Call](#create-agent-with-azure-function-call)
     - [OpenAPI](#create-agent-with-openapi)
     - [Fabric data](#create-an-agent-with-fabric)
+    - [Deep Research](#create-agent-with-deep-research)
   - [Create thread](#create-thread) with
     - [Tool resource](#create-thread-with-tool-resource)
   - [Create message](#create-message) with:
@@ -81,37 +82,96 @@ pip install azure-ai-agents
 
 ### Create and authenticate the client
 
-To construct a synchronous client:
+To use this SDK, start by creating an `AIProjectClient`. For more information on `azure-ai-projects`, refer to its [README](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/README.md).
+
+Here is an example of creating a synchronous `AIProjectClient`:
 
 ```python
 import os
-from azure.ai.agents import AgentsClient
+from azure.ai.projects import AIProjectClient
 from azure.identity import DefaultAzureCredential
 
-agents_client = AgentsClient(
+project_client = AIProjectClient(
     endpoint=os.environ["PROJECT_ENDPOINT"],
     credential=DefaultAzureCredential(),
 )
 ```
 
-To construct an asynchronous client, Install the additional package [aiohttp](https://pypi.org/project/aiohttp/):
+To construct an asynchronous client, install the `aiohttp` package:
 
 ```bash
 pip install aiohttp
 ```
 
-and update the code above to import `asyncio`, and import `AgentsClient` from the `azure.ai.agents.aio` namespace:
+Then use the code below with `AIProjectClient` and `DefaultAzureCredential` in `aio` packages:
+
+```python
+import asyncio
+import os
+from azure.ai.projects.aio import AIProjectClient
+from azure.identity.aio import DefaultAzureCredential
+
+async def main() -> None:
+    project_client = AIProjectClient(
+       endpoint=os.environ["PROJECT_ENDPOINT"],
+       credential=DefaultAzureCredential(),
+    )
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Once you have an `AIProjectClient`, you can obtain an `AgentsClient` like this:
+
+**Synchronous Client:**
+```python
+with project_client:
+    agents_client = project_client.agents
+```
+
+**Asynchronous Client:**
+```python
+async with project_client:
+    agents_client = project_client.agents
+```
+
+Alternatively, you can instantiate an AgentsClient directly as a standalone approach without using `azure-ai-projects`. However, this is not recommended, as it has limitations and lacks the integrated capabilities provided by using an `AIProjectClient`.   Here is is the example:
 
+**Synchronous Client:**
 ```python
 import os
+from azure.ai.agents import AgentsClient
+from azure.identity import DefaultAzureCredential
+
+agents_client = AgentsClient(
+    endpoint=os.environ["PROJECT_ENDPOINT"],
+    credential=DefaultAzureCredential()
+)
+
+with agents_client:
+    # your code to consume the client
+    pass
+
+```
+
+**Asynchronous Client:**
+```python
 import asyncio
+import os
 from azure.ai.agents.aio import AgentsClient
-from azure.core.credentials import AzureKeyCredential
+from azure.identity.aio import DefaultAzureCredential
 
-agent_client = AgentsClient(
-   endpoint=os.environ["PROJECT_ENDPOINT"],
-   credential=DefaultAzureCredential(),
-)
+async def main() -> None:
+    agents_client = AgentsClient(
+        endpoint=os.environ["PROJECT_ENDPOINT"],
+        credential=DefaultAzureCredential()
+    )
+    async with agents_client:
+        # your code to consume the client
+        pass
+
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
 ## Examples
@@ -311,6 +371,47 @@ with project_client:
 
 <!-- END SNIPPET -->
 
+### Create Agent with Deep Research
+
+To enable your Agent to do a detailed research of a topic, use the `DeepResearchTool` along with a connection to a Bing Grounding resource.
+This scenarios requires you to specify two model deployments. One is the generic chat model that does arbitration, and is
+specified as usual when you call the `create_agent` method. The other is the Deep Research model, which is specified
+when you define the `DeepResearchTool`.
+
+Here is an example:
+
+<!-- SNIPPET:sample_agents_deep_research.create_agent_with_deep_research_tool -->
+
+```python
+conn_id = os.environ["AZURE_BING_CONNECTION_ID"]
+
+# Initialize a Deep Research tool with Bing Connection ID and Deep Research model deployment name
+deep_research_tool = DeepResearchTool(
+    bing_grounding_connection_id=conn_id,
+    deep_research_model=os.environ["DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME"],
+)
+
+# Create Agent with the Deep Research tool and process Agent run
+with project_client:
+
+    with project_client.agents as agents_client:
+
+        # Create a new agent that has the Deep Research tool attached.
+        # NOTE: To add Deep Research to an existing agent, fetch it with `get_agent(agent_id)` and then,
+        # update the agent with the Deep Research tool.
+        agent = agents_client.create_agent(
+            model=os.environ["MODEL_DEPLOYMENT_NAME"],
+            name="my-agent",
+            instructions="You are a helpful Agent that assists in researching scientific topics.",
+            tools=deep_research_tool.definitions,
+        )
+```
+
+<!-- END SNIPPET -->
+
+> **Limitation**: The Deep Research tool is currently recommended **only** in non-streaming scenarios.
+> Using it with streaming can work, but it may occasionally time-out and is therefore not yet recommended.
+
 ### Create Agent with Azure AI Search
 
 Azure AI Search is an enterprise search system for high-performance applications. It integrates with Azure OpenAI Service and Azure Machine Learning, offering advanced search technologies like vector search and full-text search. Ideal for knowledge base insights, information discovery, and automation. Creating an Agent with Azure AI Search requires an existing Azure AI Search Index. For more information and setup guides, see [Azure AI Search Tool Guide](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/azure-ai-search?tabs=azurecli%2Cpython&pivots=overview-azure-ai-search).
@@ -320,22 +421,24 @@ Here is an example to integrate Azure AI Search:
 <!-- SNIPPET:sample_agents_azure_ai_search.create_agent_with_azure_ai_search_tool -->
 
 ```python
-conn_id = os.environ["AI_AZURE_AI_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="sample_index", query_type=AzureAISearchQueryType.SIMPLE, top_k=3, filter=""
-)
-
-# Create agent with AI search tool and process agent run
-project_client = AIProjectClient(
+with AIProjectClient(
     endpoint=os.environ["PROJECT_ENDPOINT"],
     credential=DefaultAzureCredential(),
-)
+) as project_client:
+    conn_id = project_client.connections.get_default(ConnectionType.AZURE_AI_SEARCH).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="sample_index",
+        query_type=AzureAISearchQueryType.SIMPLE,
+        top_k=3,
+        filter="",
+    )
 
-with project_client:
+    # Create agent with AI search tool and process agent run
     agents_client = project_client.agents
 
     agent = agents_client.create_agent(

sdk/ai/azure-ai-agents/_metadata.json

@@ -0,0 +1,3 @@
+{
+  "apiVersion": "2025-05-15-preview"
+}

sdk/ai/azure-ai-agents/apiview-properties.json

@@ -26,6 +26,9 @@
         "azure.ai.agents.models.CodeInterpreterToolResource": "Azure.AI.Agents.CodeInterpreterToolResource",
         "azure.ai.agents.models.ConnectedAgentDetails": "Azure.AI.Agents.ConnectedAgentDetails",
         "azure.ai.agents.models.ConnectedAgentToolDefinition": "Azure.AI.Agents.ConnectedAgentToolDefinition",
+        "azure.ai.agents.models.DeepResearchBingGroundingConnection": "Azure.AI.Agents.DeepResearchBingGroundingConnection",
+        "azure.ai.agents.models.DeepResearchDetails": "Azure.AI.Agents.DeepResearchDetails",
+        "azure.ai.agents.models.DeepResearchToolDefinition": "Azure.AI.Agents.DeepResearchToolDefinition",
         "azure.ai.agents.models.FabricDataAgentToolParameters": "Azure.AI.Agents.FabricDataAgentToolParameters",
         "azure.ai.agents.models.FileInfo": "Azure.AI.Agents.FileInfo",
         "azure.ai.agents.models.FileListResponse": "Azure.AI.Agents.FileListResponse",
@@ -101,6 +104,8 @@
         "azure.ai.agents.models.RunStepCodeInterpreterToolCall": "Azure.AI.Agents.RunStepCodeInterpreterToolCall",
         "azure.ai.agents.models.RunStepCodeInterpreterToolCallDetails": "Azure.AI.Agents.RunStepCodeInterpreterToolCallDetails",
         "azure.ai.agents.models.RunStepCompletionUsage": "Azure.AI.Agents.RunStepCompletionUsage",
+        "azure.ai.agents.models.RunStepDeepResearchToolCall": "Azure.AI.Agents.RunStepDeepResearchToolCall",
+        "azure.ai.agents.models.RunStepDeepResearchToolCallDetails": "Azure.AI.Agents.RunStepDeepResearchToolCallDetails",
         "azure.ai.agents.models.RunStepDelta": "Azure.AI.Agents.RunStepDelta",
         "azure.ai.agents.models.RunStepDeltaChunk": "Azure.AI.Agents.RunStepDeltaChunk",
         "azure.ai.agents.models.RunStepDeltaCodeInterpreterDetailItemObject": "Azure.AI.Agents.RunStepDeltaCodeInterpreterDetailItemObject",

sdk/ai/azure-ai-agents/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/ai/azure-ai-agents",
-  "Tag": "python/ai/azure-ai-agents_c924b708a0"
+  "Tag": "python/ai/azure-ai-agents_ca2235eed8"
 }