Agents IA hébergés sur Azure (Python)

Construisez des agents hébergés basés sur des conteneurs en utilisant ImageBasedHostedAgentDefinition du kit SDK Azure AI Projects.

Installation

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

Version SDK minimale : 2.0.0b3 ou ultérieure requise pour le support des agents hébergés.

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_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Conditions préalables

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

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

Authentification

Utilisez toujours DefaultAzureCredential :

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 utilisez une credential spécifique directement 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
)

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="my-hosted-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
        ],
        cpu="1",
        memory="2Gi",
        image="myregistry.azurecr.io/my-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"Created agent: {agent.name} (version: {agent.version})")

3. Lister les versions de l'agent

versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
    print(f"Version: {version.version}, State: {version.state}")

4. Supprimer une version de l'agent

client.agents.delete_version(
    agent_name="my-hosted-agent",
    version=agent.version
)

Paramètres ImageBasedHostedAgentDefinition

Versions de protocole

Le paramètre container_protocol_versions spécifie les protocoles supportés 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="myregistry.azurecr.io/my-agent:latest",
    cpu="2",      # 2 cœurs CPU
    memory="4Gi"  # 4 Gio de mémoire
)

Limites de ressources : | Ressource | Min | Max | Par 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": "my-mcp-server",
        "server_url": "https://my-mcp-server.example.com"
    }
]

Outils multiples

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

Variables d'environnement

Transmettez 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": "value"
}

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 create_hosted_agent():
    """Create a hosted agent with custom container image."""

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

    agent = client.agents.create_version(
        agent_name="data-processor-agent",
        definition=ImageBasedHostedAgentDefinition(
            container_protocol_versions=[
                ProtocolVersionRecord(
                    protocol=AgentProtocol.RESPONSES,
                    version="v1"
                )
            ],
            image="myregistry.azurecr.io/data-processor: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"Created hosted agent: {agent.name}")
    print(f"Version: {agent.version}")
    print(f"State: {agent.state}")

    return agent

if __name__ == "__main__":
    create_hosted_agent()

Motif 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 create_hosted_agent_async():
    """Create a hosted agent asynchronously."""

    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="async-agent",
                definition=ImageBasedHostedAgentDefinition(
                    container_protocol_versions=[
                        ProtocolVersionRecord(
                            protocol=AgentProtocol.RESPONSES,
                            version="v1"
                        )
                    ],
                    image="myregistry.azurecr.io/async-agent:latest",
                    cpu="1",
                    memory="2Gi"
                )
            )
            return agent

Erreurs courantes

Bonnes pratiques

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

Liens de référence

• Kit SDK Azure AI Projects
• Documentation des agents hébergés
• Azure Container Registry