Agents Hébergés Azure AI (Python)

Que fait Agents Hébergés Azure AI (Python) ?

Créez des agents hébergés conteneurisés à l'aide de ImageBasedHostedAgentDefinition du SDK Azure AI Projects.

Installation

pip install azure-ai-projects>=2.0.0b3 azure-identity

Version minimale du SDK : 2.0.0b3 ou ultérieure requise pour la prise en charge des agents hébergés.

Variables d'Environnement

AZURE_AI_PROJECT_ENDPOINT=https://<ressource>.services.ai.azure.com/api/projects/<projet>

Prérequis

Avant de créer des agents hébergés :

1. Image conteneur - Construisez et poussez-la vers Azure Container Registry (ACR)
2. Permissions de tirage ACR - Accordez à l'identité managée de votre projet le rôle AcrPull sur l'ACR
3. Environnement de capacité - Environnement de capacité au niveau du compte avec enablePublicHostingEnvironment=true
4. Version du SDK - Assurez-vous que azure-ai-projects>=2.0.0b3

Authentification

Utilisez toujours DefaultAzureCredential :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

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

Flux de Travail Principal

1. Imports

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

2. Créer un Agent Hébergé

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

agent = client.agents.create_version(
    agent_name="mon-agent-heberge",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
        ],
        cpu="1",
        memory="2Gi",
        image="monregistre.azurecr.io/mon-agent:latest",
        tools=[{"type": "code_interpreter"}],
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            "MODEL_NAME": "gpt-4o-mini"
        }
    )
)

print(f"Agent créé : {agent.name} (version : {agent.version})")

3. Lister les Versions de l'Agent

versions = client.agents.list_versions(agent_name="mon-agent-heberge")
for version in versions:
    print(f"Version : {version.version}, État : {version.state}")

4. Supprimer une Version d'Agent

client.agents.delete_version(
    agent_name="mon-agent-heberge",
    version=agent.version
)

Paramètres de ImageBasedHostedAgentDefinition

Paramètre	Type	Obligatoire	Description
container_protocol_versions	list[ProtocolVersionRecord]	Oui	Versions de protocole prises en charge par l'agent
image	str	Oui	Chemin complet de l'image conteneur (registre/image:tag)
cpu	str	Non	Allocation CPU (ex. "1", "2")
memory	str	Non	Allocation mémoire (ex. "2Gi", "4Gi")
tools	list[dict]	Non	Outils disponibles pour l'agent
environment_variables	dict[str, str]	Non	Variables d'environnement pour le conteneur

Versions de Protocole

Le paramètre container_protocol_versions spécifie les protocoles pris en charge par votre agent :

from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol

# Protocole RESPONSES - réponses standard de l'agent
container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]

Protocoles disponibles :

Protocole	Description
AgentProtocol.RESPONSES	Protocole de réponse standard pour les interactions avec l'agent

Allocation de Ressources

Spécifiez le CPU et la mémoire pour votre conteneur :

definition=ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="monregistre.azurecr.io/mon-agent:latest",
    cpu="2",      # 2 cœurs CPU
    memory="4Gi"  # 4 GiB de mémoire
)

Limites de Ressources :

Ressource	Min	Max	Défaut
CPU	0,5	4	1
Mémoire	1Gi	8Gi	2Gi

Configuration des Outils

Ajoutez des outils à votre agent hébergé :

Interpréteur de Code

tools=[{"type": "code_interpreter"}]

Outils MCP

tools=[
    {"type": "code_interpreter"},
    {
        "type": "mcp",
        "server_label": "mon-serveur-mcp",
        "server_url": "https://mon-serveur-mcp.example.com"
    }
]

Outils Multiples

tools=[
    {"type": "code_interpreter"},
    {"type": "file_search"},
    {
        "type": "mcp",
        "server_label": "outil-personnalise",
        "server_url": "https://outil-personnalise.example.com"
    }
]

Variables d'Environnement

Passez la configuration à votre conteneur :

environment_variables={
    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    "MODEL_NAME": "gpt-4o-mini",
    "LOG_LEVEL": "INFO",
    "CUSTOM_CONFIG": "valeur"
}

Bonne pratique : Ne codez jamais les secrets en dur. Utilisez des variables d'environnement ou Azure Key Vault.

Exemple Complet

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

def creer_agent_heberge():
    """Crée un agent hébergé avec une image conteneur personnalisée."""
    
    client = AIProjectClient(
        endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
        credential=DefaultAzureCredential()
    )
    
    agent = client.agents.create_version(
        agent_name="agent-traitement-donnees",
        definition=ImageBasedHostedAgentDefinition(
            container_protocol_versions=[
                ProtocolVersionRecord(
                    protocol=AgentProtocol.RESPONSES,
                    version="v1"
                )
            ],
            image="monregistre.azurecr.io/traitement-donnees:v1.0",
            cpu="2",
            memory="4Gi",
            tools=[
                {"type": "code_interpreter"},
                {"type": "file_search"}
            ],
            environment_variables={
                "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
                "MODEL_NAME": "gpt-4o-mini",
                "MAX_RETRIES": "3"
            }
        )
    )
    
    print(f"Agent hébergé créé : {agent.name}")
    print(f"Version : {agent.version}")
    print(f"État : {agent.state}")
    
    return agent

if __name__ == "__main__":
    creer_agent_heberge()

Modèle Asynchrone

import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

async def creer_agent_heberge_async():
    """Crée un agent hébergé de manière asynchrone."""
    
    async with DefaultAzureCredential() as credential:
        async with AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as client:
            agent = await client.agents.create_version(
                agent_name="agent-async",
                definition=ImageBasedHostedAgentDefinition(
                    container_protocol_versions=[
                        ProtocolVersionRecord(
                            protocol=AgentProtocol.RESPONSES,
                            version="v1"
                        )
                    ],
                    image="monregistre.azurecr.io/agent-async:latest",
                    cpu="1",
                    memory="2Gi"
                )
            )
            return agent

Erreurs Courantes

Erreur	Cause	Solution
ImagePullBackOff	Permission de tirage ACR refusée	Accordez le rôle AcrPull à l'identité managée du projet
InvalidContainerImage	Image introuvable	Vérifiez que le chemin et le tag de l'image existent dans l'ACR
CapabilityHostNotFound	Aucun environnement de capacité configuré	Créez un environnement de capacité au niveau du compte
ProtocolVersionNotSupported	Version de protocole invalide	Utilisez AgentProtocol.RESPONSES avec la version "v1"

Bonnes Pratiques

1. Versionnez vos images - Utilisez des tags spécifiques, pas latest en production
2. Ressources minimales - Commencez avec un CPU/mémoire minimum, montez en charge si nécessaire
3. Variables d'environnement - Utilisez-les pour toute configuration, ne codez jamais en dur
4. Gestion des erreurs - Encadrez la création de l'agent dans des blocs try/except
5. Nettoyage - Supprimez les versions d'agent inutilisées pour libérer des ressources

Liens de Référence

• SDK Azure AI Projects
• Documentation sur les Agents Hébergés
• Azure Container Registry

Quand Utiliser

Cette compétence doit être utilisée pour exécuter le flux de travail ou les actions décrits dans l'aperçu.

Limitations

• Utilisez cette compétence uniquement lorsque la tâche correspond clairement à la portée décrite ci-dessus.
• Ne considérez pas la sortie comme un substitut à une validation, un test ou une revue d'expert spécifique à l'environnement.
• Arrêtez-vous et demandez des clarifications si les entrées, permissions, limites de sécurité ou critères de succès requis sont manquants.