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.

Product documentation | [Samples][samples] | API reference documentation | Package (PyPI) | SDK source code

Reporting issues

To report an issue with the client library, or request additional features, please open a GitHub issue here. 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.
• 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 interface. Code samples here use DefaultAzureCredential. To get that working, you will need:
  • An appropriate role assignment. see Role-based access control in Azure AI Foundry portal. Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal.
  • Azure CLI installed.
  • You are logged into your Azure account by running az login.

Install the package

pip install azure-ai-projects

Note that the dependent package 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:

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:

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:

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 and the README.md 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 -->

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 from the 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.

Chat completions with AzureOpenAI client

<!-- SNIPPET:sample_chat_completions_with_azure_openai_client.aoai_chat_completions_sample-->

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-->

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-->

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"G