Skip to content

Commit 8cda327

Browse files
azure-sdkazure-sdk
committed
Update docs metadata
1 parent 2f7e6d2 commit 8cda327

File tree

2 files changed

+143
-40
lines changed

2 files changed

+143
-40
lines changed

‎docs-ref-services/preview/ai-agents-readme.md

Lines changed: 139 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
22
title: Azure AI Agents client library for Python
33
keywords: Azure, python, SDK, API, azure-ai-agents, ai
4-
ms.date: 06/09/2025
4+
ms.date: 06/30/2025
55
ms.topic: reference
66
ms.devlang: python
77
ms.service: ai
88
---
99
<!-- PIPY LONG DESCRIPTION BEGIN -->
10-
# Azure AI Agents client library for Python - version 1.1.0b2
10+
# Azure AI Agents client library for Python - version 1.1.0b3
1111

1212

1313
Use the AI Agents client library to:
@@ -46,6 +46,7 @@ To report an issue with the client library, or request additional features, plea
4646
- [Azure Function Call](#create-agent-with-azure-function-call)
4747
- [OpenAPI](#create-agent-with-openapi)
4848
- [Fabric data](#create-an-agent-with-fabric)
49+
- [Deep Research](#create-agent-with-deep-research)
4950
- [Create thread](#create-thread) with
5051
- [Tool resource](#create-thread-with-tool-resource)
5152
- [Create message](#create-message) with:
@@ -90,37 +91,96 @@ pip install azure-ai-agents
9091

9192
### Create and authenticate the client
9293

93-
To construct a synchronous client:
94+
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/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-projects/README.md).
95+
96+
Here is an example of creating a synchronous `AIProjectClient`:
9497

9598
```python
9699
import os
97-
from azure.ai.agents import AgentsClient
100+
from azure.ai.projects import AIProjectClient
98101
from azure.identity import DefaultAzureCredential
99102

100-
agents_client = AgentsClient(
103+
project_client = AIProjectClient(
101104
endpoint=os.environ["PROJECT_ENDPOINT"],
102105
credential=DefaultAzureCredential(),
103106
)
104107
```
105108

106-
To construct an asynchronous client, Install the additional package [aiohttp](https://pypi.org/project/aiohttp/):
109+
To construct an asynchronous client, install the `aiohttp` package:
107110

108111
```bash
109112
pip install aiohttp
110113
```
111114

112-
and update the code above to import `asyncio`, and import `AgentsClient` from the `azure.ai.agents.aio` namespace:
115+
Then use the code below with `AIProjectClient` and `DefaultAzureCredential` in `aio` packages:
116+
117+
```python
118+
import asyncio
119+
import os
120+
from azure.ai.projects.aio import AIProjectClient
121+
from azure.identity.aio import DefaultAzureCredential
122+
123+
async def main() -> None:
124+
project_client = AIProjectClient(
125+
endpoint=os.environ["PROJECT_ENDPOINT"],
126+
credential=DefaultAzureCredential(),
127+
)
128+
129+
if __name__ == "__main__":
130+
asyncio.run(main())
131+
```
132+
133+
Once you have an `AIProjectClient`, you can obtain an `AgentsClient` like this:
134+
135+
**Synchronous Client:**
136+
```python
137+
with project_client:
138+
agents_client = project_client.agents
139+
```
140+
141+
**Asynchronous Client:**
142+
```python
143+
async with project_client:
144+
agents_client = project_client.agents
145+
```
146+
147+
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:
113148

149+
**Synchronous Client:**
114150
```python
115151
import os
152+
from azure.ai.agents import AgentsClient
153+
from azure.identity import DefaultAzureCredential
154+
155+
agents_client = AgentsClient(
156+
endpoint=os.environ["PROJECT_ENDPOINT"],
157+
credential=DefaultAzureCredential()
158+
)
159+
160+
with agents_client:
161+
# your code to consume the client
162+
pass
163+
164+
```
165+
166+
**Asynchronous Client:**
167+
```python
116168
import asyncio
169+
import os
117170
from azure.ai.agents.aio import AgentsClient
118-
from azure.core.credentials import AzureKeyCredential
171+
from azure.identity.aio import DefaultAzureCredential
119172

120-
agent_client = AgentsClient(
121-
endpoint=os.environ["PROJECT_ENDPOINT"],
122-
credential=DefaultAzureCredential(),
123-
)
173+
async def main() -> None:
174+
agents_client = AgentsClient(
175+
endpoint=os.environ["PROJECT_ENDPOINT"],
176+
credential=DefaultAzureCredential()
177+
)
178+
async with agents_client:
179+
# your code to consume the client
180+
pass
181+
182+
if __name__ == "__main__":
183+
asyncio.run(main())
124184
```
125185

126186
## Examples
@@ -320,6 +380,47 @@ with project_client:
320380

321381
<!-- END SNIPPET -->
322382

383+
### Create Agent with Deep Research
384+
385+
To enable your Agent to do a detailed research of a topic, use the `DeepResearchTool` along with a connection to a Bing Grounding resource.
386+
This scenarios requires you to specify two model deployments. One is the generic chat model that does arbitration, and is
387+
specified as usual when you call the `create_agent` method. The other is the Deep Research model, which is specified
388+
when you define the `DeepResearchTool`.
389+
390+
Here is an example:
391+
392+
<!-- SNIPPET:sample_agents_deep_research.create_agent_with_deep_research_tool -->
393+
394+
```python
395+
conn_id = os.environ["AZURE_BING_CONNECTION_ID"]
396+
397+
# Initialize a Deep Research tool with Bing Connection ID and Deep Research model deployment name
398+
deep_research_tool = DeepResearchTool(
399+
bing_grounding_connection_id=conn_id,
400+
deep_research_model=os.environ["DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME"],
401+
)
402+
403+
# Create Agent with the Deep Research tool and process Agent run
404+
with project_client:
405+
406+
with project_client.agents as agents_client:
407+
408+
# Create a new agent that has the Deep Research tool attached.
409+
# NOTE: To add Deep Research to an existing agent, fetch it with `get_agent(agent_id)` and then,
410+
# update the agent with the Deep Research tool.
411+
agent = agents_client.create_agent(
412+
model=os.environ["MODEL_DEPLOYMENT_NAME"],
413+
name="my-agent",
414+
instructions="You are a helpful Agent that assists in researching scientific topics.",
415+
tools=deep_research_tool.definitions,
416+
)
417+
```
418+
419+
<!-- END SNIPPET -->
420+
421+
> **Limitation**: The Deep Research tool is currently recommended **only** in non-streaming scenarios.
422+
> Using it with streaming can work, but it may occasionally time-out and is therefore not yet recommended.
423+
323424
### Create Agent with Azure AI Search
324425

325426
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).
@@ -329,22 +430,24 @@ Here is an example to integrate Azure AI Search:
329430
<!-- SNIPPET:sample_agents_azure_ai_search.create_agent_with_azure_ai_search_tool -->
330431

331432
```python
332-
conn_id = os.environ["AI_AZURE_AI_CONNECTION_ID"]
333-
334-
print(conn_id)
335-
336-
# Initialize agent AI search tool and add the search index connection id
337-
ai_search = AzureAISearchTool(
338-
index_connection_id=conn_id, index_name="sample_index", query_type=AzureAISearchQueryType.SIMPLE, top_k=3, filter=""
339-
)
340-
341-
# Create agent with AI search tool and process agent run
342-
project_client = AIProjectClient(
433+
with AIProjectClient(
343434
endpoint=os.environ["PROJECT_ENDPOINT"],
344435
credential=DefaultAzureCredential(),
345-
)
436+
) as project_client:
437+
conn_id = project_client.connections.get_default(ConnectionType.AZURE_AI_SEARCH).id
438+
439+
print(conn_id)
440+
441+
# Initialize agent AI search tool and add the search index connection id
442+
ai_search = AzureAISearchTool(
443+
index_connection_id=conn_id,
444+
index_name="sample_index",
445+
query_type=AzureAISearchQueryType.SIMPLE,
446+
top_k=3,
447+
filter="",
448+
)
346449

347-
with project_client:
450+
# Create agent with AI search tool and process agent run
348451
agents_client = project_client.agents
349452

350453
agent = agents_client.create_agent(
@@ -390,9 +493,9 @@ for message in messages:
390493

391494
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:
392495

393-
For more details about requirements and specification of functions, refer to [Function Tool Specifications](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/FunctionTool.md)
496+
For more details about requirements and specification of functions, refer to [Function Tool Specifications](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/FunctionTool.md)
394497

395-
Here is an example to use [user functions](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/utils/user_functions.py) in `toolset`:
498+
Here is an example to use [user functions](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/utils/user_functions.py) in `toolset`:
396499
<!-- SNIPPET:sample_agents_stream_eventhandler_with_toolset.create_agent_with_function_tool -->
397500

398501
```python
@@ -411,7 +514,7 @@ agent = agents_client.create_agent(
411514

412515
<!-- END SNIPPET -->
413516

414-
For asynchronous functions, you must import `AgentsClient` from `azure.ai.agents.aio` and use `AsyncFunctionTool`. Here is an example using [asynchronous user functions](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_async/sample_agents_functions_async.py):
517+
For asynchronous functions, you must import `AgentsClient` from `azure.ai.agents.aio` and use `AsyncFunctionTool`. Here is an example using [asynchronous user functions](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_async/sample_agents_functions_async.py):
415518

416519
```python
417520
from azure.ai.agents.aio import AgentsClient
@@ -436,8 +539,8 @@ agent = await agents_client.create_agent(
436539

437540
<!-- END SNIPPET -->
438541

439-
Notice that if `enable_auto_function_calls` is called, the SDK will invoke the functions automatically during `create_and_process` or streaming. If you prefer to execute them manually, refer to [`sample_agents_stream_eventhandler_with_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_eventhandler_with_functions.py) or
440-
[`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions.py)
542+
Notice that if `enable_auto_function_calls` is called, the SDK will invoke the functions automatically during `create_and_process` or streaming. If you prefer to execute them manually, refer to [`sample_agents_stream_eventhandler_with_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_eventhandler_with_functions.py) or
543+
[`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions.py)
441544

442545
### Create Agent With Azure Function Call
443546

@@ -927,7 +1030,7 @@ message = agents_client.messages.create(
9271030

9281031
To process your message, you can use `runs.create`, `runs.create_and_process`, or `runs.stream`.
9291032

930-
`runs.create` requests the Agent to process the message without polling for the result. If you are using `function tools`, your code is responsible for polling for the result and acknowledging the status of `Run`. When the status is `requires_action`, your code is responsible for calling the function tools. For a code sample, visit [`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions.py).
1033+
`runs.create` requests the Agent to process the message without polling for the result. If you are using `function tools`, your code is responsible for polling for the result and acknowledging the status of `Run`. When the status is `requires_action`, your code is responsible for calling the function tools. For a code sample, visit [`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions.py).
9311034

9321035
Here is an example of `runs.create` and poll until the run is completed:
9331036

@@ -967,7 +1070,7 @@ run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.
9671070

9681071
<!-- END SNIPPET -->
9691072

970-
With streaming, polling need not be considered. If `function tools` were added to the agents, you should decide to have the function tools called manually or automatically. Please visit [`manual function call sample`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_eventhandler_with_functions.py) or [`automatic function call sample`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_iteration_with_toolset.py).
1073+
With streaming, polling need not be considered. If `function tools` were added to the agents, you should decide to have the function tools called manually or automatically. Please visit [`manual function call sample`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_eventhandler_with_functions.py) or [`automatic function call sample`](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_iteration_with_toolset.py).
9711074

9721075
Here is a basic example of streaming:
9731076

@@ -1049,7 +1152,7 @@ with agents_client.runs.stream(thread_id=thread.id, agent_id=agent.id, event_han
10491152

10501153
<!-- END SNIPPET -->
10511154

1052-
As you can see, this SDK parses the events and produces various event types similar to OpenAI agents. In your use case, you might not be interested in handling all these types and may decide to parse the events on your own. To achieve this, please refer to [override base event handler](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_with_base_override_eventhandler.py).
1155+
As you can see, this SDK parses the events and produces various event types similar to OpenAI agents. In your use case, you might not be interested in handling all these types and may decide to parse the events on your own. To achieve this, please refer to [override base event handler](https://github.com/Azure/azure-sdk-for-python/blob/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_with_base_override_eventhandler.py).
10531156

10541157
```
10551158
Note: Multiple streaming processes may be chained behind the scenes.
@@ -1280,7 +1383,7 @@ To report an issue with the client library, or request additional features, plea
12801383

12811384
## Next steps
12821385

1283-
Have a look at the [Samples](https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-agents_1.1.0b2/sdk/ai/azure-ai-agents/samples) folder, containing fully runnable Python code for synchronous and asynchronous clients.
1386+
Have a look at the [Samples](https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-agents_1.1.0b3/sdk/ai/azure-ai-agents/samples) folder, containing fully runnable Python code for synchronous and asynchronous clients.
12841387

12851388
Explore the [AI Starter Template](https://aka.ms/azsdk/azure-ai-agents/python/ai-starter-template). This template creates an Azure AI Foundry hub, project and connected resources including Azure OpenAI Service, AI Search and more. It also deploys a simple chat application to Azure Container Apps.
12861389

@@ -1305,9 +1408,9 @@ additional questions or comments.
13051408
[samples]: https://aka.ms/azsdk/azure-ai-projects/python/samples/
13061409
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
13071410
[entra_id]: https://learn.microsoft.com/azure/ai-services/authentication?tabs=powershell#authenticate-with-microsoft-entra-id
1308-
[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-agents_1.1.0b2/sdk/identity/azure-identity#credentials
1411+
[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-agents_1.1.0b3/sdk/identity/azure-identity#credentials
13091412
[azure_identity_pip]: https://pypi.org/project/azure-identity/
1310-
[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-agents_1.1.0b2/sdk/identity/azure-identity#defaultazurecredential
1413+
[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-agents_1.1.0b3/sdk/identity/azure-identity#defaultazurecredential
13111414
[pip]: https://pypi.org/project/pip/
13121415
[azure_sub]: https://azure.microsoft.com/free/
13131416
[evaluators]: https://learn.microsoft.com/azure/ai-studio/how-to/develop/evaluate-sdk

‎metadata/preview/azure-ai-agents.json

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"Name": "azure-ai-agents",
3-
"Version": "1.1.0b2",
3+
"Version": "1.1.0b3",
44
"DevVersion": null,
55
"DirectoryPath": "sdk/ai/azure-ai-agents",
66
"ServiceDirectory": "ai",
@@ -10,17 +10,17 @@
1010
"SdkType": "client",
1111
"IsNewSdk": true,
1212
"ArtifactName": "azure-ai-agents",
13-
"ReleaseStatus": "2025-06-09",
13+
"ReleaseStatus": "2025-06-30",
1414
"IncludedForValidation": false,
1515
"AdditionalValidationPackages": [
1616
""
1717
],
1818
"ArtifactDetails": {
19+
"name": "azure-ai-agents",
1920
"triggeringPaths": [
2021
"/sdk/ai/ci.yml"
2122
],
22-
"safeName": "azureaiagents",
23-
"name": "azure-ai-agents"
23+
"safeName": "azureaiagents"
2424
},
2525
"CIParameters": {
2626
"CIMatrixConfigs": []

0 commit comments

Comments
 (0)