Azure AI Projects Python SDK (Foundry SDK)

Construisez des applications IA sur Microsoft Foundry en utilisant le SDK azure-ai-projects.

Installation

pip install azure-ai-projects azure-identity

Variables d'environnement

AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"  # Requis pour toutes les méthodes d'authentification
AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Requis pour toutes les méthodes d'authentification
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Authentification

import os
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
from azure.ai.projects import AIProjectClient

# Dev local : DefaultAzureCredential. Production : définir AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utiliser directement une authentification spécifique en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=credential,
)

Vue d'ensemble des opérations client

Deux approches client

1. AIProjectClient (Foundry natif)

from azure.ai.projects import AIProjectClient

client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# Utiliser les opérations natives de Foundry
agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are helpful.",
)

2. Client compatible OpenAI

# Obtenir le client compatible OpenAI à partir du projet
openai_client = client.get_openai_client()

# Utiliser l'API OpenAI standard
response = openai_client.chat.completions.create(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    messages=[{"role": "user", "content": "Hello!"}],
)

Opérations agent

Créer un agent (basique)

agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="my-agent",
    instructions="You are a helpful assistant.",
)

Créer un agent avec outils

from azure.ai.agents import CodeInterpreterTool, FileSearchTool

agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="tool-agent",
    instructions="You can execute code and search files.",
    tools=[CodeInterpreterTool(), FileSearchTool()],
)

Agents versionnés avec PromptAgentDefinition

from azure.ai.projects.models import PromptAgentDefinition

# Créer un agent versionné
agent_version = client.agents.create_version(
    agent_name="customer-support-agent",
    definition=PromptAgentDefinition(
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        instructions="You are a customer support specialist.",
        tools=[],  # Ajouter des outils selon les besoins
    ),
    version_label="v1.0",
)

Voir references/agents.md pour les patterns agent détaillés.

Vue d'ensemble des outils

Voir references/tools.md pour tous les patterns d'outils.

Flux thread et messages

# 1. Créer un thread
thread = client.agents.threads.create()

# 2. Ajouter un message
client.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="What's the weather like?",
)

# 3. Créer et traiter un run
run = client.agents.runs.create_and_process(
    thread_id=thread.id,
    agent_id=agent.id,
)

# 4. Obtenir la réponse
if run.status == "completed":
    messages = client.agents.messages.list(thread_id=thread.id)
    for msg in messages:
        if msg.role == "assistant":
            print(msg.content[0].text.value)

Connexions

# Lister toutes les connexions
connections = client.connections.list()
for conn in connections:
    print(f"{conn.name}: {conn.connection_type}")

# Obtenir une connexion spécifique
connection = client.connections.get(connection_name="my-search-connection")

Voir references/connections.md pour les patterns de connexion.

Déploiements

# Lister les déploiements de modèles disponibles
deployments = client.deployments.list()
for deployment in deployments:
    print(f"{deployment.name}: {deployment.model}")

Voir references/deployments.md pour les patterns de déploiement.

Datasets et index

# Lister les datasets
datasets = client.datasets.list()

# Lister les index
indexes = client.indexes.list()

Voir references/datasets-indexes.md pour les opérations de données.

Évaluation

# Utiliser le client OpenAI pour les evals
openai_client = client.get_openai_client()

# Créer une évaluation avec des évaluateurs intégrés
eval_run = openai_client.evals.runs.create(
    eval_id="my-eval",
    name="quality-check",
    data_source={
        "type": "custom",
        "item_references": [{"item_id": "test-1"}],
    },
    testing_criteria=[
        {"type": "fluency"},
        {"type": "task_adherence"},
    ],
)

Voir references/evaluation.md pour les patterns d'évaluation.

Client asynchrone

from azure.ai.projects.aio import AIProjectClient

async with AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
) as client:
    agent = await client.agents.create_agent(...)
    # ... opérations asynchrones

Voir references/async-patterns.md pour les patterns asynchrones.

Mémoires persistantes

# Créer une mémoire persistante pour l'agent
memory_store = client.agents.create_memory_store(
    name="conversation-memory",
)

# Attacher à l'agent pour la mémoire persistante
agent = client.agents.create_agent(
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    name="memory-agent",
    tools=[MemorySearchTool()],
    tool_resources={"memory": {"store_ids": [memory_store.id]}},
)

Bonnes pratiques

1. Utiliser les gestionnaires de contexte pour le client asynchrone : async with AIProjectClient(...) as client:
2. Nettoyer les agents quand c'est terminé : client.agents.delete_agent(agent.id)
3. Utiliser create_and_process pour les runs simples, streaming pour l'UX en temps réel
4. Utiliser des agents versionnés pour les déploiements en production
5. Préférer les connexions pour l'intégration de services externes (AI Search, Bing, etc.)

Comparaison SDK

Fichiers de référence

• references/agents.md: Opérations agent avec PromptAgentDefinition
• references/tools.md: Tous les outils agent avec exemples
• references/evaluation.md: Vue d'ensemble des opérations d'évaluation
• references/built-in-evaluators.md: Référence complète des évaluateurs intégrés
• references/custom-evaluators.md: Patterns d'évaluateurs basés sur le code et les prompts
• references/connections.md: Opérations de connexion
• references/deployments.md: Énumération des déploiements
• references/datasets-indexes.md: Opérations de dataset et index
• references/async-patterns.md: Utilisation du client asynchrone
• references/api-reference.md: Référence API complète pour les 373 exports SDK (v2.0.0b4)
• scripts/run_batch_evaluation.py: Outil CLI pour les évaluations en batch