Skip to content

Commit 64a3a39

Browse files
dargilcodargilco
committed
Minor updates to ref-docs and package README
1 parent 3f3567f commit 64a3a39

21 files changed

+113
-68
lines changed

‎sdk/ai/azure-ai-projects/README.md‎

Lines changed: 61 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@
33
The AI Projects client library (in preview) is part of the Azure AI Foundry SDK, and provides easy access to
44
resources in your Azure AI Foundry Project. Use it to:
55

6-
* **Create and run Agents** using the `.agents` property on the client.
7-
* **Get an AzureOpenAI client** using the `.inference.get_azure_openai_client` method.
8-
* **Enumerate AI Models** deployed to your Foundry Project using the `.deployments` operations.
9-
* **Enumerate connected Azure resources** in your Foundry project using the `.connections` operations.
10-
* **Upload documents and create Datasets** to reference them using the `.datasets` operations.
11-
* **Create and enumerate Search Indexes** using the `.indexes` operations.
6+
* **Create and run Agents** using methods on the `.agents` client property.
7+
* **Get an AzureOpenAI client** using the `.get_openai_client()` client method.
8+
* **Enumerate AI Models** deployed to your Foundry Project using methods on the `.deployments` client property.
9+
* **Enumerate connected Azure resources** in your Foundry project using methods on the `.connections` client property.
10+
* **Upload documents and create Datasets** to reference them using methods on the `.datasets` client property.
11+
* **Create and enumerate Search Indexes** using methods on the `.indexes` client property.
1212

13-
The client library uses the version `v1` of the AI Foundry [data plane REST APIs](https://aka.ms/azsdk/azure-ai-projects/ga-rest-api-reference).
13+
The client library uses version `v1` of the AI Foundry [data plane REST APIs](https://aka.ms/azsdk/azure-ai-projects/ga-rest-api-reference).
1414

1515
[Product documentation](https://aka.ms/azsdk/azure-ai-projects/product-doc)
1616
| [Samples][samples]
@@ -29,7 +29,7 @@ To report an issue with the client library, or request additional features, plea
2929
- Python 3.9 or later.
3030
- An [Azure subscription][azure_sub].
3131
- A [project in Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects).
32-
- The project endpoint URL of the form `https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>`. It can be found in your Azure AI Foundry Project overview page. Below we will assume the environment variable `PROJECT_ENDPOINT` was defined to hold this value.
32+
- The project endpoint URL of the form `https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name`. It can be found in your Azure AI Foundry Project overview page. Below we will assume the environment variable `PROJECT_ENDPOINT` was defined to hold this value.
3333
- An Entra ID token for authentication. Your application needs an object that implements the [TokenCredential](https://learn.microsoft.com/python/api/azure-core/azure.core.credentials.tokencredential) interface. Code samples here use [DefaultAzureCredential](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential). To get that working, you will need:
3434
* An appropriate role assignment. see [Role-based access control in Azure AI Foundry portal](https://learn.microsoft.com/azure/ai-foundry/concepts/rbac-ai-foundry). Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal.
3535
* [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed.
@@ -41,6 +41,8 @@ To report an issue with the client library, or request additional features, plea
4141
pip install azure-ai-projects
4242
```
4343

44+
Note that the dependent package [azure-ai-agents](https://pypi.org/project/azure-ai-agents/) will be install as a result, if not already installed, to support `.agent` operations on the client.
45+
4446
## Key concepts
4547

4648
### Create and authenticate the client with Entra ID
@@ -66,29 +68,32 @@ To construct an asynchronous client, Install the additional package [aiohttp](ht
6668
pip install aiohttp
6769
```
6870

69-
and update the code above to import `asyncio`, and import `AIProjectClient` from the `azure.ai.projects.aio` namespace:
71+
and update the code above to import `asyncio`, import `AIProjectClient` from the `azure.ai.projects.aio` package, and import `DefaultAzureCredential` from the `azure.identity.aio` package:
7072

7173
```python
7274
import os
7375
import asyncio
7476
from azure.ai.projects.aio import AIProjectClient
75-
from azure.core.credentials import AzureKeyCredential
77+
from azure.identity.aio import DefaultAzureCredential
7678

77-
project_client = AIProjectClient.from_connection_string(
79+
project_client = AIProjectClient(
7880
credential=DefaultAzureCredential(),
7981
endpoint=os.environ["PROJECT_ENDPOINT"],
8082
)
8183
```
8284

83-
**Note:** Support for project connection string and hub-based projects has been discontinued. We recommend creating a new Azure AI Foundry resource utilizing project endpoint. If this is not possible, please pin the version of or pin the version of `azure-ai-projects` to `1.0.0b10` or earlier.
85+
**Note:** Support for project connection string and hub-based projects has been discontinued. We recommend creating a new Azure AI Foundry resource utilizing project endpoint. If this is not possible, please pin the version of `azure-ai-projects` to `1.0.0b10` or earlier.
8486

8587
## Examples
8688

8789
### Performing Agent operations
8890

8991
The `.agents` property on the `AIProjectsClient` gives you access to an authenticated `AgentsClient` from the `azure-ai-agents` package. Below we show how to create an Agent and delete it. To see what you can do with the Agent you created, see the [many samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-agents/samples) and the [README.md](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-agents) file of the dependent `azure-ai-agents` package.
9092

91-
The code below assumes `model_deployment_name` (a string) is defined. It's the deployment name of an AI model in your Foundry Project, as shown in the "Models + endpoints" tab, under the "Name" column.
93+
The code below assumes the following:
94+
95+
* `model_deployment_name` (a string) is defined. It's the deployment name of an AI model in your Foundry Project, as shown in the "Models + endpoints" tab, under the "Name" column.
96+
* `connection_name` (a string) is defined. It's the name of the connection to a resource of type "Azure OpenAI", as shown in the "Connected resources" tab, under the "Name" column, in the "Management Center" of your Foundry Project.
9297

9398
<!-- SNIPPET:sample_agents.agents_sample -->
9499

@@ -111,17 +116,19 @@ print("Deleted agent")
111116

112117
### Get an authenticated AzureOpenAI client
113118

114-
Your Azure AI Foundry project may have one or more AI models deployed that support chat completions.
119+
Your Azure AI Foundry project may have one or more AI models deployed that support chat completions or responses.
115120
These could be OpenAI models, Microsoft models, or models from other providers.
116121
Use the code below to get an authenticated [AzureOpenAI](https://github.com/openai/openai-python?tab=readme-ov-file#microsoft-azure-openai)
117-
from the [openai](https://pypi.org/project/openai/) package, and execute a chat completions call.
122+
from the [openai](https://pypi.org/project/openai/) package, and execute a chat completions or responses calls.
118123

119124
The code below assumes `model_deployment_name` (a string) is defined. It's the deployment name of an AI model in your
120125
Foundry Project, or a connected Azure OpenAI resource. As shown in the "Models + endpoints" tab, under the "Name" column.
121126

122-
Update the `api_version` value with one found in the "Data plane - inference" row [in this table](https://learn.microsoft.com/azure/ai-services/openai/reference#api-specs).
127+
Update the `api_version` value with one found in the "Data plane - inference" row [in this table](https://learn.microsoft.com/azure/ai-foundry/openai/reference#api-specs).
128+
129+
#### Chat completions with AzureOpenAI client
123130

124-
<!-- SNIPPET:sample_chat_completions_with_azure_openai_client.aoai_sample-->
131+
<!-- SNIPPET:sample_chat_completions_with_azure_openai_client.aoai_chat_completions_sample-->
125132

126133
```python
127134
print(
@@ -163,6 +170,42 @@ with project_client.get_openai_client(api_version="2024-10-21", connection_name=
163170

164171
See the "inference" folder in the [package samples][samples] for additional samples.
165172

173+
#### Responses with AzureOpenAI client
174+
175+
<!-- SNIPPET:sample_responses_with_azure_openai_client.aoai_responses_sample-->
176+
177+
```python
178+
print(
179+
"Get an authenticated Azure OpenAI client for the parent AI Services resource, and perform a 'responses' operation:"
180+
)
181+
with project_client.get_openai_client(api_version="2025-04-01-preview") as client:
182+
183+
response = client.responses.create(
184+
model=model_deployment_name,
185+
input="How many feet are in a mile?",
186+
)
187+
188+
print(response.output_text)
189+
190+
print(
191+
"Get an authenticated Azure OpenAI client for a connected Azure OpenAI service, and perform a 'responses' operation:"
192+
)
193+
with project_client.get_openai_client(
194+
api_version="2025-04-01-preview", connection_name=connection_name
195+
) as client:
196+
197+
response = client.responses.create(
198+
model=model_deployment_name,
199+
input="How many feet are in a mile?",
200+
)
201+
202+
print(response.output_text)
203+
```
204+
205+
<!-- END SNIPPET -->
206+
207+
See the "inference" folder in the [package samples][samples] for additional samples.
208+
166209
### Deployments operations
167210

168211
The code below shows some Deployments operations, which allow you to enumerate the AI models deployed to your AI Foundry Projects. These models can be seen in the "Models + endpoints" tab in your AI Foundry Project. Full samples can be found under the "deployment" folder in the [package samples][samples].
@@ -393,7 +436,7 @@ By default logs redact the values of URL query strings, the values of some HTTP
393436
project_client = AIProjectClient(
394437
credential=DefaultAzureCredential(),
395438
endpoint=os.environ["PROJECT_ENDPOINT"],
396-
logging_enable = True
439+
logging_enable=True
397440
)
398441
```
399442

‎sdk/ai/azure-ai-projects/azure/ai/projects/_client.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,10 @@ class AIProjectClient:
3434
:ivar deployments: DeploymentsOperations operations
3535
:vartype deployments: azure.ai.projects.operations.DeploymentsOperations
3636
:param endpoint: Project endpoint. In the form
37-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/_project"
37+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/_project"
3838
if your Foundry Hub has only one Project, or to use the default Project in your Hub. Or in the
3939
form
40-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>"
40+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name"
4141
if you want to explicitly
4242
specify the Foundry Project name. Required.
4343
:type endpoint: str

‎sdk/ai/azure-ai-projects/azure/ai/projects/_configuration.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ class AIProjectClientConfiguration: # pylint: disable=too-many-instance-attribu
2323
attributes.
2424
2525
:param endpoint: Project endpoint. In the form
26-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/_project"
26+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/_project"
2727
if your Foundry Hub has only one Project, or to use the default Project in your Hub. Or in the
2828
form
29-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>"
29+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name"
3030
if you want to explicitly
3131
specify the Foundry Project name. Required.
3232
:type endpoint: str

‎sdk/ai/azure-ai-projects/azure/ai/projects/_patch.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,9 @@ class AIProjectClient(AIProjectClientGenerated): # pylint: disable=too-many-ins
9393
:ivar deployments: DeploymentsOperations operations
9494
:vartype deployments: azure.ai.projects.operations.DeploymentsOperations
9595
:param endpoint: Project endpoint. In the form
96-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/_project"
96+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/_project"
9797
if your Foundry Hub has only one Project, or to use the default Project in your Hub. Or in the
98-
form "https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>"
98+
form "https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name"
9999
if you want to explicitly specify the Foundry Project name. Required.
100100
:type endpoint: str
101101
:param credential: Credential used to authenticate requests to the service. Required.
@@ -139,14 +139,14 @@ def agents(self) -> AgentsClient: # type: ignore[name-defined]
139139
def get_openai_client(
140140
self, *, api_version: Optional[str] = None, connection_name: Optional[str] = None, **kwargs
141141
) -> "OpenAI": # type: ignore[name-defined]
142-
"""Get an authenticated OpenAI client (from the `openai` package) to use with
142+
"""Get an authenticated AzureOpenAI client (from the `openai` package) to use with
143143
AI models deployed to your AI Foundry Project or connected Azure OpenAI services.
144144
145145
.. note:: The package `openai` must be installed prior to calling this method.
146146
147147
:keyword api_version: The Azure OpenAI api-version to use when creating the client. Optional.
148148
See "Data plane - Inference" row in the table at
149-
https://learn.microsoft.com/azure/ai-services/openai/reference#api-specs. If this keyword
149+
https://learn.microsoft.com/azure/ai-foundry/openai/reference#api-specs. If this keyword
150150
is not specified, you must set the environment variable `OPENAI_API_VERSION` instead.
151151
:paramtype api_version: Optional[str]
152152
:keyword connection_name: Optional. If specified, the connection named here must be of type Azure OpenAI.
@@ -156,8 +156,8 @@ def get_openai_client(
156156
with AI models deployed directly to your AI Foundry project.
157157
:paramtype connection_name: Optional[str]
158158
159-
:return: An authenticated OpenAI client
160-
:rtype: ~openai.OpenAI
159+
:return: An authenticated AzureOpenAI client
160+
:rtype: ~openai.AzureOpenAI
161161
162162
:raises ~azure.core.exceptions.ResourceNotFoundError: if an Azure OpenAI connection
163163
does not exist.

‎sdk/ai/azure-ai-projects/azure/ai/projects/aio/_client.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,10 @@ class AIProjectClient:
3434
:ivar deployments: DeploymentsOperations operations
3535
:vartype deployments: azure.ai.projects.aio.operations.DeploymentsOperations
3636
:param endpoint: Project endpoint. In the form
37-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/_project"
37+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/_project"
3838
if your Foundry Hub has only one Project, or to use the default Project in your Hub. Or in the
3939
form
40-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>"
40+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name"
4141
if you want to explicitly
4242
specify the Foundry Project name. Required.
4343
:type endpoint: str

‎sdk/ai/azure-ai-projects/azure/ai/projects/aio/_configuration.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ class AIProjectClientConfiguration: # pylint: disable=too-many-instance-attribu
2323
attributes.
2424
2525
:param endpoint: Project endpoint. In the form
26-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/_project"
26+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/_project"
2727
if your Foundry Hub has only one Project, or to use the default Project in your Hub. Or in the
2828
form
29-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>"
29+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name"
3030
if you want to explicitly
3131
specify the Foundry Project name. Required.
3232
:type endpoint: str

‎sdk/ai/azure-ai-projects/azure/ai/projects/aio/_patch.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -58,9 +58,9 @@ class AIProjectClient(AIProjectClientGenerated): # pylint: disable=too-many-ins
5858
:ivar deployments: DeploymentsOperations operations
5959
:vartype deployments: azure.ai.projects.aio.operations.DeploymentsOperations
6060
:param endpoint: Project endpoint. In the form
61-
"https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/_project"
61+
"https://your-ai-services-account-name.services.ai.azure.com/api/projects/_project"
6262
if your Foundry Hub has only one Project, or to use the default Project in your Hub. Or in the
63-
form "https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>"
63+
form "https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name"
6464
if you want to explicitly specify the Foundry Project name. Required.
6565
:type endpoint: str
6666
:param credential: Credential used to authenticate requests to the service. Required.
@@ -104,14 +104,14 @@ def agents(self) -> AgentsClient: # type: ignore[name-defined]
104104
async def get_openai_client(
105105
self, *, api_version: Optional[str] = None, connection_name: Optional[str] = None, **kwargs
106106
) -> "AsyncOpenAI": # type: ignore[name-defined]
107-
"""Get an authenticated AsyncOpenAI client (from the `openai` package) to use with
107+
"""Get an authenticated AsyncAzureOpenAI client (from the `openai` package) to use with
108108
AI models deployed to your AI Foundry Project or connected Azure OpenAI services.
109109
110110
.. note:: The package `openai` must be installed prior to calling this method.
111111
112112
:keyword api_version: The Azure OpenAI api-version to use when creating the client. Optional.
113113
See "Data plane - Inference" row in the table at
114-
https://learn.microsoft.com/azure/ai-services/openai/reference#api-specs. If this keyword
114+
https://learn.microsoft.com/azure/ai-foundry/openai/reference#api-specs. If this keyword
115115
is not specified, you must set the environment variable `OPENAI_API_VERSION` instead.
116116
:paramtype api_version: Optional[str]
117117
:keyword connection_name: Optional. If specified, the connection named here must be of type Azure OpenAI.

‎sdk/ai/azure-ai-projects/samples/inference/azure-ai-inference/sample_chat_completions_with_azure_ai_inference_client.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@
3333
endpoint = os.environ["PROJECT_ENDPOINT"]
3434
model_deployment_name = os.environ["MODEL_DEPLOYMENT_NAME"]
3535

36-
# Project endpoint has the form: https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>
37-
# Inference endpoint has the form: https://<your-ai-services-account-name>.services.ai.azure.com/models
38-
# Strip the "/api/projects/<your-project-name>" part and replace with "/models":
36+
# Project endpoint has the form: https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name
37+
# Inference endpoint has the form: https://your-ai-services-account-name.services.ai.azure.com/models
38+
# Strip the "/api/projects/your-project-name" part and replace with "/models":
3939
inference_endpoint = f"https://{urlparse(endpoint).netloc}/models"
4040

4141
with DefaultAzureCredential(exclude_interactive_browser_credential=False) as credential:

‎sdk/ai/azure-ai-projects/samples/inference/azure-ai-inference/sample_chat_completions_with_azure_ai_inference_client_and_azure_monitor_tracing.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,9 @@
5050
connection_string = project_client.telemetry.get_application_insights_connection_string()
5151
configure_azure_monitor(connection_string=connection_string)
5252

53-
# Project endpoint has the form: https://<your-ai-services-account-name>.services.ai.azure.com/api/projects/<your-project-name>
54-
# Inference endpoint has the form: https://<your-ai-services-account-name>.services.ai.azure.com/models
55-
# Strip the "/api/projects/<your-project-name>" part and replace with "/models":
53+
# Project endpoint has the form: https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name
54+
# Inference endpoint has the form: https://your-ai-services-account-name.services.ai.azure.com/models
55+
# Strip the "/api/projects/your-project-name" part and replace with "/models":
5656
inference_endpoint = f"https://{urlparse(endpoint).netloc}/models"
5757

5858
with tracer.start_as_current_span(scenario):

0 commit comments

Comments
 (0)