# Azure AI Projects client library for Python
The AI Projects client library (in preview) is part of the Azure AI Foundry SDK, and provides easy access to
resources in your Azure AI Foundry Project. Use it to:
* **Create and run Agents** using methods on the `.agents` client property.
* **Get an AzureOpenAI client** using the `.get_openai_client()` client method.
* **Enumerate AI Models** deployed to your Foundry Project using methods on the `.deployments` client property.
* **Enumerate connected Azure resources** in your Foundry project using methods on the `.connections` client property.
* **Upload documents and create Datasets** to reference them using methods on the `.datasets` client property.
* **Create and enumerate Search Indexes** using methods on the `.indexes` client property.
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).
[Product documentation](https://aka.ms/azsdk/azure-ai-projects/product-doc)
| [Samples][samples]
| [API reference documentation](https://aka.ms/azsdk/azure-ai-projects/python/reference)
| [Package (PyPI)](https://aka.ms/azsdk/azure-ai-projects/python/package)
| [SDK source code](https://aka.ms/azsdk/azure-ai-projects/python/code)
## Reporting issues
To report an issue with the client library, or request additional features, please open a [GitHub issue here](https://github.com/Azure/azure-sdk-for-python/issues). Mention the package name "azure-ai-projects" in the title or content.
## Getting started
### Prerequisite
- Python 3.9 or later.
- An [Azure subscription][azure_sub].
- A [project in Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects).
- 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.
- 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:
* 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.
* [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed.
* You are logged into your Azure account by running `az login`.
### Install the package
```bash
pip install azure-ai-projects
```
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.
## Key concepts
### Create and authenticate the client with Entra ID
Entra ID is the only authentication method supported at the moment by the client.
To construct a synchronous client:
```python
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
credential=DefaultAzureCredential(),
endpoint=os.environ["PROJECT_ENDPOINT"],
)
```
To construct an asynchronous client, Install the additional package [aiohttp](https://pypi.org/project/aiohttp/):
```bash
pip install aiohttp
```
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:
```python
import os
import asyncio
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import DefaultAzureCredential
project_client = AIProjectClient(
credential=DefaultAzureCredential(),
endpoint=os.environ["PROJECT_ENDPOINT"],
)
```
**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.
## Examples
### Performing Agent operations
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.
The code below assumes the following:
* `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.
* `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.
<!-- SNIPPET:sample_agents.agents_sample -->
```python
agent = project_client.agents.create_agent(
model=model_deployment_name,
name="my-agent",
instructions="You are helpful agent",
)
print(f"Created agent, agent ID: {agent.id}")
# Do something with your Agent!
# See samples here https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-agents/samples
project_client.agents.delete_agent(agent.id)
print("Deleted agent")
```
<!-- END SNIPPET -->
### Get an authenticated AzureOpenAI client
Your Azure AI Foundry project may have one or more AI models deployed that support chat completions or responses.
These could be OpenAI models, Microsoft models, or models from other providers.
Use the code below to get an authenticated [AzureOpenAI](https://github.com/openai/openai-python?tab=readme-ov-file#microsoft-azure-openai)
from the [openai](https://pypi.org/project/openai/) package, and execute a chat completions or responses calls.
The code below assumes `model_deployment_name` (a string) is defined. It's the deployment name of an AI model in your
Foundry Project, or a connected Azure OpenAI resource. As shown in the "Models + endpoints" tab, under the "Name" column.
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).
#### Chat completions with AzureOpenAI client
<!-- SNIPPET:sample_chat_completions_with_azure_openai_client.aoai_chat_completions_sample-->
```python
print(
"Get an authenticated Azure OpenAI client for the parent AI Services resource, and perform a chat completion operation:"
)
with project_client.get_openai_client(api_version="2024-10-21") as client:
response = client.chat.completions.create(
model=model_deployment_name,
messages=[
{
"role": "user",
"content": "How many feet are in a mile?",
},
],
)
print(response.choices[0].message.content)
print(
"Get an authenticated Azure OpenAI client for a connected Azure OpenAI service, and perform a chat completion operation:"
)
with project_client.get_openai_client(api_version="2024-10-21", connection_name=connection_name) as client:
response = client.chat.completions.create(
model=model_deployment_name,
messages=[
{
"role": "user",
"content": "How many feet are in a mile?",
},
],
)
print(response.choices[0].message.content)
```
<!-- END SNIPPET -->
See the "inference" folder in the [package samples][samples] for additional samples.
#### Responses with AzureOpenAI client
<!-- SNIPPET:sample_responses_with_azure_openai_client.aoai_responses_sample-->
```python
print(
"Get an authenticated Azure OpenAI client for the parent AI Services resource, and perform a 'responses' operation:"
)
with project_client.get_openai_client(api_version="2025-04-01-preview") as client:
response = client.responses.create(
model=model_deployment_name,
input="How many feet are in a mile?",
)
print(response.output_text)
print(
"Get an authenticated Azure OpenAI client for a connected Azure OpenAI service, and perform a 'responses' operation:"
)
with project_client.get_openai_client(
api_version="2025-04-01-preview", connection_name=connection_name
) as client:
response = client.responses.create(
model=model_deployment_name,
input="How many feet are in a mile?",
)
print(response.output_text)
```
<!-- END SNIPPET -->
See the "inference" folder in the [package samples][samples] for additional samples.
### Deployments operations
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].
<!-- SNIPPET:sample_deployments.deployments_sample-->
```python
print("List all deployments:")
for deployment in project_client.deployments.list():
print(deployment)
print(f"List all deployments by the model publisher `{model_publisher}`:")
for deployment in project_client.deployments.list(model_publisher=model_publisher):
print(deployment)
print(f"List all deployments of model `{model_name}`:")
for deployment in project_client.deployments.list(model_name=model_name):
print(deployment)
print(f"Get a single deployment named `{model_deployment_name}`:")
deployment = project_client.deployments.get(model_deployment_name)
print(deployment)
# At the moment, the only deployment type supported is ModelDeployment
if isinstance(deployment, ModelDeployment):
print(f"Type: {deployment.type}")
print(f"Name: {deployment.name}")
print(f"Model Name: {deployment.model_name}")
print(f"Model Version: {deployment.model_version}")
print(f"Model Publisher: {deployment.model_publisher}")
print(f"Capabilities: {deployment.capabilities}")
print(f"SKU: {deployment.sku}")
print(f"Connection Name: {deployment.connection_name}")
```
<!-- END SNIPPET -->
### Connections operations
The code below shows some Connection operations, which allow you to enumerate the Azure Resources connected to your AI Foundry Projects. These connections can be seen in the "Management Center", in the "Connected resources" tab in your AI Foundry Project. Full samples can be found under the "connections" folder in the [package samples][samples].
<!-- SNIPPET:sample_connections.connections_sample-->
```python
print("List all connections:")
for connection in project_client.connections.list():
print(connection)
print("List all connections of a particular type:")
for connection in project_client.connections.list(
connection_type=ConnectionType.AZURE_OPEN_AI,
):
print(connection)
print("Get the default connection of a particular type, without its credentials:")
connection = project_client.connections.get_default(connection_type=ConnectionType.AZURE_OPEN_AI)
print(connection)
print("Get the default connection of a particular type, with its credentials:")
connection = project_client.connections.get_default(
connection_type=ConnectionType.AZURE_OPEN_AI, include_credentials=True
)
print(connection)
print(f"Get the connection named `{connection_name}`, without its credentials:")
connection = project_client.connections.get(connection_name)
print(connection)
print(f"Get the connection named `{connection_name}`, with its credentials:")
connection = project_client.connections.get(connection_name, include_credentials=True)
print(connection)
```
<!-- END SNIPPET -->
### Dataset operations
The code below shows some Dataset operations. Full samples can be found under the "datasets"
folder in the [package samples][samples].
<!-- SNIPPET:sample_datasets.datasets_sample-->
```python
print(
f"Upload a single file and create a new Dataset `{dataset_name}`, version `{dataset_version_1}`, to reference the file."
)
dataset: DatasetVersion = project_client.datasets.upload_file(
name=dataset_name,
version=dataset_version_1,
file_path=data_file,
connection_name=connection_name,
)
print(dataset)
print(
f"Upload files in a folder (including sub-folders) and create a new version `{dataset_version_2}` in the same Dataset, to reference the files."
)
dataset = project_client.datasets.upload_folder(
name=dataset_name,
version=dataset_version_2,
folder=data_folder,
connection_name=connection_name,
file_pattern=re.compile(r"\.(txt|csv|md)$", re.IGNORECASE),
)
print(dataset)
print(f"Get an existing Dataset version `{dataset_version_1}`:")
dataset = project_client.datasets.get(name=dataset_name, version=dataset_version_1)
print(dataset)
print(f"Get credentials of an existing Dataset version `{dataset_version_1}`:")
dataset_credential = project_client.datasets.get_credentials(name=dataset_name, version=dataset_version_1)
print(dataset_credential)
print("List latest versions of all Datasets:")
for dataset in project_client.datasets.list():
print(dataset)
print(f"Listing all versions of the Dataset named `{dataset_name}`:")
for dataset in project_client.datasets.list_versions(name=dataset_name):
print(dataset)
print("Delete all Dataset versions created above:")
project_client.datasets.delete(name=dataset_name, version=dataset_version_1)
project_client.datasets.delete(name=dataset_name, version=dataset_version_2)
```
<!-- END SNIPPET -->
### Indexes operations
The code below shows some Indexes operations. Full samples can be found under the "indexes"
folder in the [package samples][samples].
<!-- SNIPPET:sample_indexes.indexes_sample-->
```python
print(
f"Create Index `{index_name}` with version `{index_version}`, referencing an existing AI Search resource:"
)
index = project_client.indexes.create_or_update(
name=index_name,
version=index_version,
index=AzureAISearchIndex(connection_name=ai_search_connection_name, index_name=ai_search_index_name),
)
print(index)
print(f"Get Index `{index_name}` version `{index_version}`:")
index = project_client.indexes.get(name=index_name, version=index_version)
print(index)
print("List latest versions of all Indexes:")
for index in project_client.indexes.list():
print(index)
print(f"Listing all versions of the Index named `{index_name}`:")
for index in project_client.indexes.list_versions(name=index_name):
print(index)
print(f"Delete Index `{index_name}` version `{index_version}`:")
project_client.indexes.delete(name=index_name, version=index_version)
```
<!-- END SNIPPET -->
## Tracing
The AI Projects client library can be configured to emit OpenTelemetry traces for all its REST API calls. These can be viewed in the "Tracing" tab in your AI Foundry Project page, once you add an Application Insights resource and configured your application appropriately. Agent operations (via the `.agents` property) can also be instrumented, as well as OpenAI client library operations (client created by calling `get_openai_client()` method). For local debugging purposes, traces can also be omitted to the console. For more information see:
* [Trace AI applications using OpenAI SDK](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/trace-application)
* Chat-completion samples with console or Azure Monitor tracing enabled. See `samples\inference\azure-openai` folder.
* The Tracing section in the [README.md file of the azure-ai-agents package](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/README.md#tracing).
## Troubleshooting
### Exceptions
Client methods that make service calls raise an [HttpResponseError](https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions.httpresponseerror) exception for a non-success HTTP status code response from the service. The exception's `status_code` will hold the HTTP response status code (with `reason` showing the friendly name). The exception's `error.message` contains a detailed message that may be helpful in diagnosing the issue:
```python
from azure.core.exceptions import HttpResponseError
...
try:
result = project_client.connections.list()
except HttpResponseError as e:
print(f"Status code: {e.status_code} ({e.reason})")
print(e.message)
```
For example, when you provide wrong credentials:
```text
Status code: 401 (Unauthorized)
Operation returned an invalid status 'Unauthorized'
```
### Logging
The client uses the standard [Python logging library](https://docs.python.org/3/library/logging.html). The SDK logs HTTP request and response details, which may be useful in troubleshooting. To log to stdout, add the following at the top of your Python script:
```python
import sys
import logging
# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.inference' libraries.
logger = logging.getLogger("azure")
# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.DEBUG)
# Direct logging output to stdout:
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename="sample.log")
logger.addHandler(handler)
# Optional: change the default logging format. Here we add a timestamp.
#formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
#handler.setFormatter(formatter)
```
By default logs redact the values of URL query strings, the values of some HTTP request and response headers (including `Authorization` which holds the key or token), and the request and response payloads. To create logs without redaction, add `logging_enable=True` to the client constructor:
```python
project_client = AIProjectClient(
credential=DefaultAzureCredential(),
endpoint=os.environ["PROJECT_ENDPOINT"],
logging_enable=True
)
```
Note that the log level must be set to `logging.DEBUG` (see above code). Logs will be redacted with any other log level.
Be sure to protect non redacted logs to avoid compromising security.
For more information, see [Configure logging in the Azure libraries for Python](https://aka.ms/azsdk/python/logging)
### Reporting issues
To report an issue with the client library, or request additional features, please open a [GitHub issue here](https://github.com/Azure/azure-sdk-for-python/issues). Mention the package name "azure-ai-projects" in the title or content.
## Next steps
Have a look at the [Samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects/samples) folder, containing fully runnable Python code for synchronous and asynchronous clients.
## Contributing
This project welcomes contributions and suggestions. Most contributions require
you to agree to a Contributor License Agreement (CLA) declaring that you have
the right to, and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether
you need to provide a CLA and decorate the PR appropriately (e.g., label,
comment). Simply follow the instructions provided by the bot. You will only
need to do this once across all repos using our CLA.
This project has adopted the
[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
see the Code of Conduct FAQ or contact opencode@microsoft.com with any
additional questions or comments.
<!-- LINKS -->
[samples]: https://aka.ms/azsdk/azure-ai-projects/python/samples/
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
[azure_sub]: https://azure.microsoft.com/free/
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects",
"name": "azure-ai-projects",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "azure sdk, azure, ai, agents, foundry, inference, chat completion, project",
"author": "Microsoft Corporation",
"author_email": "azpysdkhelp@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/dd/95/9c04cb5f658c7f856026aa18432e0f0fa254ead2983a3574a0f5558a7234/azure_ai_projects-1.0.0.tar.gz",
"platform": null,
"description": "# Azure AI Projects client library for Python\n\nThe AI Projects client library (in preview) is part of the Azure AI Foundry SDK, and provides easy access to\nresources in your Azure AI Foundry Project. Use it to:\n\n* **Create and run Agents** using methods on the `.agents` client property.\n* **Get an AzureOpenAI client** using the `.get_openai_client()` client method.\n* **Enumerate AI Models** deployed to your Foundry Project using methods on the `.deployments` client property.\n* **Enumerate connected Azure resources** in your Foundry project using methods on the `.connections` client property.\n* **Upload documents and create Datasets** to reference them using methods on the `.datasets` client property.\n* **Create and enumerate Search Indexes** using methods on the `.indexes` client property.\n\nThe client library uses version `v1` of the AI Foundry [data plane REST APIs](https://aka.ms/azsdk/azure-ai-projects/ga-rest-api-reference).\n\n[Product documentation](https://aka.ms/azsdk/azure-ai-projects/product-doc)\n| [Samples][samples]\n| [API reference documentation](https://aka.ms/azsdk/azure-ai-projects/python/reference)\n| [Package (PyPI)](https://aka.ms/azsdk/azure-ai-projects/python/package)\n| [SDK source code](https://aka.ms/azsdk/azure-ai-projects/python/code)\n\n## Reporting issues\n\nTo report an issue with the client library, or request additional features, please open a [GitHub issue here](https://github.com/Azure/azure-sdk-for-python/issues). Mention the package name \"azure-ai-projects\" in the title or content.\n\n## Getting started\n\n### Prerequisite\n\n- Python 3.9 or later.\n- An [Azure subscription][azure_sub].\n- A [project in Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects).\n- 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.\n- 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:\n * 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.\n * [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed.\n * You are logged into your Azure account by running `az login`.\n\n### Install the package\n\n```bash\npip install azure-ai-projects\n```\n\nNote 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.\n\n## Key concepts\n\n### Create and authenticate the client with Entra ID\n\nEntra ID is the only authentication method supported at the moment by the client.\n\nTo construct a synchronous client:\n\n```python\nimport os\nfrom azure.ai.projects import AIProjectClient\nfrom azure.identity import DefaultAzureCredential\n\nproject_client = AIProjectClient(\n credential=DefaultAzureCredential(),\n endpoint=os.environ[\"PROJECT_ENDPOINT\"],\n)\n```\n\nTo construct an asynchronous client, Install the additional package [aiohttp](https://pypi.org/project/aiohttp/):\n\n```bash\npip install aiohttp\n```\n\nand 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:\n\n```python\nimport os\nimport asyncio\nfrom azure.ai.projects.aio import AIProjectClient\nfrom azure.identity.aio import DefaultAzureCredential\n\nproject_client = AIProjectClient(\n credential=DefaultAzureCredential(),\n endpoint=os.environ[\"PROJECT_ENDPOINT\"],\n)\n```\n\n**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.\n\n## Examples\n\n### Performing Agent operations\n\nThe `.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.\n\nThe code below assumes the following:\n\n* `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.\n* `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.\n\n<!-- SNIPPET:sample_agents.agents_sample -->\n\n```python\nagent = project_client.agents.create_agent(\n model=model_deployment_name,\n name=\"my-agent\",\n instructions=\"You are helpful agent\",\n)\nprint(f\"Created agent, agent ID: {agent.id}\")\n\n# Do something with your Agent!\n# See samples here https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-agents/samples\n\nproject_client.agents.delete_agent(agent.id)\nprint(\"Deleted agent\")\n```\n\n<!-- END SNIPPET -->\n\n### Get an authenticated AzureOpenAI client\n\nYour Azure AI Foundry project may have one or more AI models deployed that support chat completions or responses.\nThese could be OpenAI models, Microsoft models, or models from other providers.\nUse the code below to get an authenticated [AzureOpenAI](https://github.com/openai/openai-python?tab=readme-ov-file#microsoft-azure-openai)\nfrom the [openai](https://pypi.org/project/openai/) package, and execute a chat completions or responses calls.\n\nThe code below assumes `model_deployment_name` (a string) is defined. It's the deployment name of an AI model in your\nFoundry Project, or a connected Azure OpenAI resource. As shown in the \"Models + endpoints\" tab, under the \"Name\" column.\n\nUpdate 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).\n\n#### Chat completions with AzureOpenAI client\n\n<!-- SNIPPET:sample_chat_completions_with_azure_openai_client.aoai_chat_completions_sample-->\n\n```python\nprint(\n \"Get an authenticated Azure OpenAI client for the parent AI Services resource, and perform a chat completion operation:\"\n)\nwith project_client.get_openai_client(api_version=\"2024-10-21\") as client:\n\n response = client.chat.completions.create(\n model=model_deployment_name,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"How many feet are in a mile?\",\n },\n ],\n )\n\n print(response.choices[0].message.content)\n\nprint(\n \"Get an authenticated Azure OpenAI client for a connected Azure OpenAI service, and perform a chat completion operation:\"\n)\nwith project_client.get_openai_client(api_version=\"2024-10-21\", connection_name=connection_name) as client:\n\n response = client.chat.completions.create(\n model=model_deployment_name,\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"How many feet are in a mile?\",\n },\n ],\n )\n\n print(response.choices[0].message.content)\n```\n\n<!-- END SNIPPET -->\n\nSee the \"inference\" folder in the [package samples][samples] for additional samples.\n\n#### Responses with AzureOpenAI client\n\n<!-- SNIPPET:sample_responses_with_azure_openai_client.aoai_responses_sample-->\n\n```python\nprint(\n \"Get an authenticated Azure OpenAI client for the parent AI Services resource, and perform a 'responses' operation:\"\n)\nwith project_client.get_openai_client(api_version=\"2025-04-01-preview\") as client:\n\n response = client.responses.create(\n model=model_deployment_name,\n input=\"How many feet are in a mile?\",\n )\n\n print(response.output_text)\n\nprint(\n \"Get an authenticated Azure OpenAI client for a connected Azure OpenAI service, and perform a 'responses' operation:\"\n)\nwith project_client.get_openai_client(\n api_version=\"2025-04-01-preview\", connection_name=connection_name\n) as client:\n\n response = client.responses.create(\n model=model_deployment_name,\n input=\"How many feet are in a mile?\",\n )\n\n print(response.output_text)\n```\n\n<!-- END SNIPPET -->\n\nSee the \"inference\" folder in the [package samples][samples] for additional samples.\n\n### Deployments operations\n\nThe 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].\n\n<!-- SNIPPET:sample_deployments.deployments_sample-->\n\n```python\nprint(\"List all deployments:\")\nfor deployment in project_client.deployments.list():\n print(deployment)\n\nprint(f\"List all deployments by the model publisher `{model_publisher}`:\")\nfor deployment in project_client.deployments.list(model_publisher=model_publisher):\n print(deployment)\n\nprint(f\"List all deployments of model `{model_name}`:\")\nfor deployment in project_client.deployments.list(model_name=model_name):\n print(deployment)\n\nprint(f\"Get a single deployment named `{model_deployment_name}`:\")\ndeployment = project_client.deployments.get(model_deployment_name)\nprint(deployment)\n\n# At the moment, the only deployment type supported is ModelDeployment\nif isinstance(deployment, ModelDeployment):\n print(f\"Type: {deployment.type}\")\n print(f\"Name: {deployment.name}\")\n print(f\"Model Name: {deployment.model_name}\")\n print(f\"Model Version: {deployment.model_version}\")\n print(f\"Model Publisher: {deployment.model_publisher}\")\n print(f\"Capabilities: {deployment.capabilities}\")\n print(f\"SKU: {deployment.sku}\")\n print(f\"Connection Name: {deployment.connection_name}\")\n```\n\n<!-- END SNIPPET -->\n\n### Connections operations\n\nThe code below shows some Connection operations, which allow you to enumerate the Azure Resources connected to your AI Foundry Projects. These connections can be seen in the \"Management Center\", in the \"Connected resources\" tab in your AI Foundry Project. Full samples can be found under the \"connections\" folder in the [package samples][samples].\n\n<!-- SNIPPET:sample_connections.connections_sample-->\n\n```python\nprint(\"List all connections:\")\nfor connection in project_client.connections.list():\n print(connection)\n\nprint(\"List all connections of a particular type:\")\nfor connection in project_client.connections.list(\n connection_type=ConnectionType.AZURE_OPEN_AI,\n):\n print(connection)\n\nprint(\"Get the default connection of a particular type, without its credentials:\")\nconnection = project_client.connections.get_default(connection_type=ConnectionType.AZURE_OPEN_AI)\nprint(connection)\n\nprint(\"Get the default connection of a particular type, with its credentials:\")\nconnection = project_client.connections.get_default(\n connection_type=ConnectionType.AZURE_OPEN_AI, include_credentials=True\n)\nprint(connection)\n\nprint(f\"Get the connection named `{connection_name}`, without its credentials:\")\nconnection = project_client.connections.get(connection_name)\nprint(connection)\n\nprint(f\"Get the connection named `{connection_name}`, with its credentials:\")\nconnection = project_client.connections.get(connection_name, include_credentials=True)\nprint(connection)\n```\n\n<!-- END SNIPPET -->\n\n### Dataset operations\n\nThe code below shows some Dataset operations. Full samples can be found under the \"datasets\"\nfolder in the [package samples][samples].\n\n<!-- SNIPPET:sample_datasets.datasets_sample-->\n\n```python\nprint(\n f\"Upload a single file and create a new Dataset `{dataset_name}`, version `{dataset_version_1}`, to reference the file.\"\n)\ndataset: DatasetVersion = project_client.datasets.upload_file(\n name=dataset_name,\n version=dataset_version_1,\n file_path=data_file,\n connection_name=connection_name,\n)\nprint(dataset)\n\nprint(\n f\"Upload files in a folder (including sub-folders) and create a new version `{dataset_version_2}` in the same Dataset, to reference the files.\"\n)\ndataset = project_client.datasets.upload_folder(\n name=dataset_name,\n version=dataset_version_2,\n folder=data_folder,\n connection_name=connection_name,\n file_pattern=re.compile(r\"\\.(txt|csv|md)$\", re.IGNORECASE),\n)\nprint(dataset)\n\nprint(f\"Get an existing Dataset version `{dataset_version_1}`:\")\ndataset = project_client.datasets.get(name=dataset_name, version=dataset_version_1)\nprint(dataset)\n\nprint(f\"Get credentials of an existing Dataset version `{dataset_version_1}`:\")\ndataset_credential = project_client.datasets.get_credentials(name=dataset_name, version=dataset_version_1)\nprint(dataset_credential)\n\nprint(\"List latest versions of all Datasets:\")\nfor dataset in project_client.datasets.list():\n print(dataset)\n\nprint(f\"Listing all versions of the Dataset named `{dataset_name}`:\")\nfor dataset in project_client.datasets.list_versions(name=dataset_name):\n print(dataset)\n\nprint(\"Delete all Dataset versions created above:\")\nproject_client.datasets.delete(name=dataset_name, version=dataset_version_1)\nproject_client.datasets.delete(name=dataset_name, version=dataset_version_2)\n```\n\n<!-- END SNIPPET -->\n\n### Indexes operations\n\nThe code below shows some Indexes operations. Full samples can be found under the \"indexes\"\nfolder in the [package samples][samples].\n\n<!-- SNIPPET:sample_indexes.indexes_sample-->\n\n```python\nprint(\n f\"Create Index `{index_name}` with version `{index_version}`, referencing an existing AI Search resource:\"\n)\nindex = project_client.indexes.create_or_update(\n name=index_name,\n version=index_version,\n index=AzureAISearchIndex(connection_name=ai_search_connection_name, index_name=ai_search_index_name),\n)\nprint(index)\n\nprint(f\"Get Index `{index_name}` version `{index_version}`:\")\nindex = project_client.indexes.get(name=index_name, version=index_version)\nprint(index)\n\nprint(\"List latest versions of all Indexes:\")\nfor index in project_client.indexes.list():\n print(index)\n\nprint(f\"Listing all versions of the Index named `{index_name}`:\")\nfor index in project_client.indexes.list_versions(name=index_name):\n print(index)\n\nprint(f\"Delete Index `{index_name}` version `{index_version}`:\")\nproject_client.indexes.delete(name=index_name, version=index_version)\n```\n\n<!-- END SNIPPET -->\n\n## Tracing\n\nThe AI Projects client library can be configured to emit OpenTelemetry traces for all its REST API calls. These can be viewed in the \"Tracing\" tab in your AI Foundry Project page, once you add an Application Insights resource and configured your application appropriately. Agent operations (via the `.agents` property) can also be instrumented, as well as OpenAI client library operations (client created by calling `get_openai_client()` method). For local debugging purposes, traces can also be omitted to the console. For more information see:\n\n* [Trace AI applications using OpenAI SDK](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/trace-application)\n* Chat-completion samples with console or Azure Monitor tracing enabled. See `samples\\inference\\azure-openai` folder.\n* The Tracing section in the [README.md file of the azure-ai-agents package](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/README.md#tracing).\n\n## Troubleshooting\n\n### Exceptions\n\nClient methods that make service calls raise an [HttpResponseError](https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions.httpresponseerror) exception for a non-success HTTP status code response from the service. The exception's `status_code` will hold the HTTP response status code (with `reason` showing the friendly name). The exception's `error.message` contains a detailed message that may be helpful in diagnosing the issue:\n\n```python\nfrom azure.core.exceptions import HttpResponseError\n\n...\n\ntry:\n result = project_client.connections.list()\nexcept HttpResponseError as e:\n print(f\"Status code: {e.status_code} ({e.reason})\")\n print(e.message)\n```\n\nFor example, when you provide wrong credentials:\n\n```text\nStatus code: 401 (Unauthorized)\nOperation returned an invalid status 'Unauthorized'\n```\n\n### Logging\n\nThe client uses the standard [Python logging library](https://docs.python.org/3/library/logging.html). The SDK logs HTTP request and response details, which may be useful in troubleshooting. To log to stdout, add the following at the top of your Python script:\n\n```python\nimport sys\nimport logging\n\n# Acquire the logger for this client library. Use 'azure' to affect both\n# 'azure.core` and `azure.ai.inference' libraries.\nlogger = logging.getLogger(\"azure\")\n\n# Set the desired logging level. logging.INFO or logging.DEBUG are good options.\nlogger.setLevel(logging.DEBUG)\n\n# Direct logging output to stdout:\nhandler = logging.StreamHandler(stream=sys.stdout)\n# Or direct logging output to a file:\n# handler = logging.FileHandler(filename=\"sample.log\")\nlogger.addHandler(handler)\n\n# Optional: change the default logging format. Here we add a timestamp.\n#formatter = logging.Formatter(\"%(asctime)s:%(levelname)s:%(name)s:%(message)s\")\n#handler.setFormatter(formatter)\n```\n\nBy default logs redact the values of URL query strings, the values of some HTTP request and response headers (including `Authorization` which holds the key or token), and the request and response payloads. To create logs without redaction, add `logging_enable=True` to the client constructor:\n\n```python\nproject_client = AIProjectClient(\n credential=DefaultAzureCredential(),\n endpoint=os.environ[\"PROJECT_ENDPOINT\"],\n logging_enable=True\n)\n```\n\nNote that the log level must be set to `logging.DEBUG` (see above code). Logs will be redacted with any other log level.\n\nBe sure to protect non redacted logs to avoid compromising security.\n\nFor more information, see [Configure logging in the Azure libraries for Python](https://aka.ms/azsdk/python/logging)\n\n### Reporting issues\n\nTo report an issue with the client library, or request additional features, please open a [GitHub issue here](https://github.com/Azure/azure-sdk-for-python/issues). Mention the package name \"azure-ai-projects\" in the title or content.\n\n## Next steps\n\nHave a look at the [Samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects/samples) folder, containing fully runnable Python code for synchronous and asynchronous clients.\n\n## Contributing\n\nThis project welcomes contributions and suggestions. Most contributions require\nyou to agree to a Contributor License Agreement (CLA) declaring that you have\nthe right to, and actually do, grant us the rights to use your contribution.\nFor details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether\nyou need to provide a CLA and decorate the PR appropriately (e.g., label,\ncomment). Simply follow the instructions provided by the bot. You will only\nneed to do this once across all repos using our CLA.\n\nThis project has adopted the\n[Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,\nsee the Code of Conduct FAQ or contact opencode@microsoft.com with any\nadditional questions or comments.\n\n<!-- LINKS -->\n[samples]: https://aka.ms/azsdk/azure-ai-projects/python/samples/\n[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/\n[azure_sub]: https://azure.microsoft.com/free/\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure AI Projects Client Library for Python",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects"
},
"split_keywords": [
"azure sdk",
" azure",
" ai",
" agents",
" foundry",
" inference",
" chat completion",
" project"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b5db7149cdf71e12d9737f186656176efc94943ead4f205671768c1549593efe",
"md5": "b64e8a4d9a415382e09c7369565259de",
"sha256": "81369ed7a2f84a65864f57d3fa153e16c30f411a1504d334e184fb070165a3fa"
},
"downloads": -1,
"filename": "azure_ai_projects-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b64e8a4d9a415382e09c7369565259de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 115188,
"upload_time": "2025-07-31T02:09:29",
"upload_time_iso_8601": "2025-07-31T02:09:29.362529Z",
"url": "https://files.pythonhosted.org/packages/b5/db/7149cdf71e12d9737f186656176efc94943ead4f205671768c1549593efe/azure_ai_projects-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd959c04cb5f658c7f856026aa18432e0f0fa254ead2983a3574a0f5558a7234",
"md5": "78290872cd8e8490cd1372bc66578d2f",
"sha256": "b5f03024ccf0fd543fbe0f5abcc74e45b15eccc1c71ab87fc71c63061d9fd63c"
},
"downloads": -1,
"filename": "azure_ai_projects-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "78290872cd8e8490cd1372bc66578d2f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 130798,
"upload_time": "2025-07-31T02:09:27",
"upload_time_iso_8601": "2025-07-31T02:09:27.912694Z",
"url": "https://files.pythonhosted.org/packages/dd/95/9c04cb5f658c7f856026aa18432e0f0fa254ead2983a3574a0f5558a7234/azure_ai_projects-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 02:09:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-ai-projects"
}
JSON
