Azure AI Projects Client Library

2.0.1 · active · verified Sat Apr 11

The Azure AI Projects Client Library for Python provides client access to manage Azure AI Studio resources, including projects, connections, and deployments. It is currently at version 2.0.1 and is actively developed by Microsoft, with regular updates to support new Azure AI Studio features and API versions.

Common errors

```
ImportError: cannot import name 'FilePurpose' from 'azure.ai.projects.models'
```
cause The 'FilePurpose' class is not present in the 'azure.ai.projects.models' module, possibly due to version changes or incorrect module usage.

fix Ensure you are using the correct module and class names as per the latest SDK documentation, and verify that your 'azure-ai-projects' package is up to date.
```
ImportError: cannot import name 'PromptAgentDefinition' from 'azure.ai.projects.models'
```
cause The 'PromptAgentDefinition' class does not exist in the 'azure.ai.projects.models' module, likely due to SDK updates or documentation mismatches.

fix Review the latest SDK documentation to find the correct class or method to use, and update your code accordingly.
```
ModuleNotFoundError: No module named 'azure.ai'
```
cause The 'azure-ai' package is not installed in your Python environment.

fix Install the required package using 'pip install azure-ai-projects'.
```
ModuleNotFoundError: No module named 'azure.ai.projects'
```
cause The `azure-ai-projects` package or its required submodules are not installed in the current Python environment, or there's a typo in the import statement.

fix Install the package using pip: `pip install azure-ai-projects` and ensure your import statement is correct, e.g., `from azure.ai.projects import AIProjectClient`.
```
TypeError: AIProjectClient.__init__() missing 3 required positional arguments: 'subscription_id', 'resource_group_name', and 'project_name'
```
cause The `AIProjectClient` is being initialized without providing the mandatory `subscription_id`, `resource_group_name`, and `project_name` parameters.

fix Initialize the client with all required parameters, typically retrieved from environment variables or Azure CLI: ```python from azure.ai.projects import AIProjectClient from azure.identity import DefaultAzureCredential client = AIProjectClient( credential=DefaultAzureCredential(), subscription_id="your-subscription-id", resource_group_name="your-resource-group", project_name="your-project-name" ) ```

Warnings

breaking Version 2.0.0 introduced significant API changes and a new design for interacting with Azure AI Studio. Code written for 1.x versions will likely require substantial updates.
Fix: Refer to the official Azure SDK documentation and samples for version 2.x. Key classes and methods have changed their signatures and object models. Migrate to the new `AIStudioClient` and its associated operations.
gotcha Authentication requires proper setup for `DefaultAzureCredential`. Without correct environment variables or Azure CLI login, the client will fail to authenticate.
Fix: Ensure `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` environment variables are set, or that you are logged in via `az login` with the Azure CLI. If using Managed Identity, ensure the identity has the necessary roles (e.g., 'Contributor' or specific AI Studio roles).
gotcha Operations often require context like `subscription_id` and `resource_group_name` for client initialization, and potentially the specific AI Studio project name for resource-specific actions.
Fix: Always provide the correct `subscription_id` and `resource_group_name` when initializing the `AIStudioClient`. For operations on specific resources, ensure you pass the correct resource name or ID as arguments.

Install

pip install azure-ai-projects azure-identity Install core and authentication libraries

Imports

AIStudioClient

from azure.ai.projects import AIStudioClient

DefaultAzureCredential
```
from azure.identity import DefaultAzureCredential
```
Standard Azure SDK authentication class, common for all Azure services.

Quickstart

This quickstart demonstrates how to authenticate with Azure AI Studio using `DefaultAzureCredential` and list AI projects within a specified resource group. Ensure your environment is configured for Azure authentication (e.g., `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`, or logged in via Azure CLI).

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIStudioClient

# Replace with your Azure Subscription ID and Resource Group Name
subscription_id = os.environ.get("AZURE_SUBSCRIPTION_ID", "YOUR_SUBSCRIPTION_ID")
resource_group_name = os.environ.get("AZURE_RESOURCE_GROUP", "YOUR_RESOURCE_GROUP_NAME")
project_name = os.environ.get("AZURE_AI_PROJECT_NAME", "my-ai-project")

try:
    # Authenticate using DefaultAzureCredential
    # This will try various methods: environment variables, managed identity, Azure CLI, etc.
    credential = DefaultAzureCredential()

    # Create a client for Azure AI Studio Projects
    client = AIStudioClient(
        credential=credential,
        subscription_id=subscription_id,
        resource_group_name=resource_group_name,
    )

    # List projects within the specified resource group
    print(f"Listing projects in resource group '{resource_group_name}'...")
    projects_iterator = client.projects.list(resource_group_name=resource_group_name)
    for project in projects_iterator:
        print(f"- Project Name: {project.name}, Location: {project.location}")

    # Example: Get a specific project (if it exists)
    # Make sure 'project_name' exists in your resource group
    # project = client.projects.get(project_name=project_name)
    # print(f"\nRetrieved project: {project.name}, ID: {project.id}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure AZURE_SUBSCRIPTION_ID, AZURE_RESOURCE_GROUP, and other necessary credentials are set.")

view raw JSON →