Déployer un agent hébergé

Cet article vous montre comment déployer un agent conteneurisé sur Foundry Agent Service à l’aide du KIT de développement logiciel (SDK) Python ou de l’API REST. Utilisez ces approches lorsque vous souhaitez gérer les déploiements d’agents directement à partir de vos propres applications ou services.

Si vous effectuez un déploiement pour la première fois ou souhaitez le chemin le plus rapide, utilisez le guide de démarrage rapide : Créer et déployer un agent hébergé à la place. Le démarrage rapide utilise Azure Developer CLI (azd) ou l’extension VS Code, qui gèrent automatiquement la génération, l’envoi, la gestion des versions et la configuration RBAC.

Cycle de vie du déploiement

Chaque déploiement d’agent hébergé suit cette séquence :

1. Build et push : empaqueter votre code d’agent dans une image conteneur et l’envoyer à Azure Container Registry.
2. Créer une version d’agent : enregistrer l’image auprès de Foundry Agent Service. La plateforme provisionne l’infrastructure et crée une identité d’agent Entra dédiée.
3. Interroger l’état : attendre que l’état de la version atteigne active.
4. Appel : envoyer des demandes au point de terminaison dédié de l’agent.

Conditions préalables

• Un projet Microsoft Foundry.
• Code de l’agent utilisant un cadre pris en charge.
• Docker Desktop installé pour le développement de conteneurs local.
• Azure CLI version 2.80 ou ultérieure.

Autorisations requises

Vous avez besoin d'Azure AI Project Manager dans le cadre du projet pour créer et déployer des agents hébergés. Ce rôle inclut à la fois les autorisations de plan de données pour créer des agents et la possibilité d’attribuer le rôle Azure utilisateur IA au rôle d’agent créé par la plateforme. L’identité de l’agent a besoin de Azure AI User sur le projet pour accéder aux modèles et artefacts en temps d'exécution.

Si vous utilisez azd ou l’extension VS Code, les outils gèrent automatiquement la plupart des affectations RBAC, notamment :

• Lecteur du référentiel de registre de conteneurs pour l’identité managée du projet (extractions d’images)
• Utilisateur Azure AI pour l’identité d'agent créée par la plateforme (modèle d’exécution et accès aux outils)

Pour plus d’informations, consultez Authentification et autorisation.

Exigences pour les conteneurs

Votre image conteneur doit répondre aux exigences suivantes pour s’exécuter sur la plateforme d’agent hébergée.

Bibliothèques de protocole

Les agents hébergés communiquent avec la passerelle Foundry via des bibliothèques de protocole. Choisissez le protocole qui correspond au modèle d’interaction de votre agent :

Un conteneur unique peut exposer les deux protocoles simultanément en déclarant à la fois lorsque vous créez l’agent ( dans le agent.yaml fichier, l’appel du SDK ou la demande d’API REST) et en important les deux bibliothèques. Utilisez les bibliothèques de protocole dans votre infrastructure existante, que ce soit Microsoft Framework Agent, LangChain ou du code personnalisé.

Points de terminaison d’intégrité

Les bibliothèques de protocole exposent automatiquement un point de terminaison /readiness pour les vérifications d’intégrité de la plateforme. Vous n’avez pas besoin d’implémenter cela vous-même.

Port

Les conteneurs servent le trafic sur le port 8088 localement. En production, la passerelle Foundry gère le routage : votre conteneur n’a pas besoin d’exposer un port public.

Variables d’environnement injectées par la plateforme

La plateforme d’agent hébergé injecte automatiquement des variables d’environnement dans votre conteneur au moment de l’exécution. Votre code peut les lire sans les déclarer dans agent.yaml ou environment_variables. Le préfixe FOUNDRY_* est strictement réservé à l’usage de la plateforme.

Ne rééclarez pas les variables injectées par la plateforme . agent.yaml Elles sont définies automatiquement.

Les variables que vous déclarez vous-même, comme MODEL_DEPLOYMENT_NAME ou les points de terminaison MCP de l'outil de développement, se trouvent dans la section environment_variables de agent.yaml ou dans l'appel SDK create_version.

Empaqueter et tester votre agent localement

Avant de déployer sur Foundry, vérifiez que votre agent fonctionne localement à l’aide de la bibliothèque de protocole. Le conteneur sert les mêmes points de terminaison localement qu’en production.

Tester le protocole de Réponses

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Tester le protocole Invocations

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

Déployez à l'aide de l'Azure Developer CLI ou de Visual Studio Code

L’interface CLI Azure développeur (azd) et l’extension VS Code automatisent le cycle de vie complet du déploiement. Pour obtenir une procédure pas à pas, consultez le guide de démarrage rapide : Créer et déployer un agent hébergé.

Déployer à l’aide du Kit de développement logiciel (SDK) Python

Utilisez le Kit de développement logiciel (SDK) lorsque vous souhaitez gérer les déploiements d’agents directement à partir de Python code.

Prérequis supplémentaires

• Python 3.10 ou version ultérieure

• Image conteneur dans Azure Container Registry

• Rôle de référentiel Container Registry ou AcrPush sur le registre de conteneurs (pour pousser des images)

• Azure SDK AI Projects version 2.1.0 ou ultérieure

  pip install "azure-ai-projects>=2.1.0"
  

Générer et pousser votre image de conteneur

1. Générez votre image Docker :

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Consultez des exemples de fichiers Dockerfiles pour Python et C#.

2. Pousser vers Azure Container Registry :

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

Configurer des autorisations de registre de conteneurs

Accordez l’accès à l’identité managée de votre projet pour extraire des images :

1. Dans le portail Azure, accédez à votre ressource de projet Foundry.

2. Sélectionnez Identité et copiez l’ID d’objet (principal) sous Système affecté.

3. Attribuez le rôle Lecteur du référentiel du registre de conteneurs à cette identité sur votre registre de conteneurs. Consultez Azure Container Registry rôles et autorisations.

Créer une version de l’agent hébergé

La création d’une version déclenche la plateforme pour approvisionner l’agent automatiquement. Il n’existe aucune étape de démarrage distincte : la plateforme génère un instantané de conteneur et rend l’agent prêt à traiter les demandes.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

Pour exposer les deux protocoles, passez les deux dans container_protocol_versions:

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0")
],

Paramètres clés :

Interroger l’état de la version

Après la création d’une version, interrogez jusqu’à ce que son statut atteigne active avant de solliciter l’agent. L’approvisionnement prend généralement moins d’une minute en fonction de la taille de l’image.

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

Valeurs d’état de version :

Appeler l’agent

Une fois que la version atteint le statut active, utilisez get_openai_client pour créer un client OpenAI lié au point de terminaison de l’agent.

Pour le protocole Réponses :

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

Pour le protocole Invocations , appelez directement le point de terminaison d’appel :

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

Pour obtenir des exemples plus complets, consultez les exemples d’agents hébergés.

Déployer à l’aide de l’API REST

Utilisez l’API REST pour les déploiements basés sur HTTP directs ou lors de l’intégration à des outils personnalisés.

Avant de commencer, générez et envoyez (push) votre image conteneur et configurez les autorisations de registre de conteneurs.

Configurer des variables

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

Créer un agent

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

La création d’un agent crée également une version 1 et déclenche l’approvisionnement.

Interroger l’état de la version

Interrogez le point de terminaison de version jusqu'à ce que status soit active :

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

Appeler l’agent

Utilisez le point de terminaison dédié de l’agent pour envoyer des demandes. Définir "stream": true pour recevoir les événements envoyés par le serveur.

Protocole réponses :

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

Protocole d’appel :

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

Créer une nouvelle version

Déployez le code ou la configuration mis à jour en créant une nouvelle version :

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Nettoyer les ressources

Pour éviter les frais, nettoyez les ressources une fois terminées. Les ressources de calcul de l’agent sont désactivées après 15 minutes d’inactivité, donc il n’y a aucun coût lorsqu’un agent ne traite pas de requêtes.

Nettoyage de l’Azure Developer CLI

azd down

Nettoyage du Kit de développement logiciel (SDK

Supprimez une seule version :

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

Ou supprimez l’ensemble de l’agent et toutes ses versions :

project.agents.delete(agent_name="my-agent")

Nettoyage de l’API REST

Supprimez une seule version :

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Ou supprimez l’agent entier :

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Dépannage

Les erreurs d’approvisionnement s’affichent sur les champs error.code et error.message de l’objet de version. Vérifiez l’état de la version après la création pour identifier les problèmes.

Pour les erreurs 5xx, contactez Microsoft support technique.

Pour connaître les exigences RBAC détaillées et la résolution des problèmes d’autorisation, consultez les informations de référence sur les autorisations de l’agent hébergé.

Étapes suivantes

Contenu connexe

• Qu’est-ce que les agents hébergés ?
• Concepts d’identité de l’agent
• Applications d’agent
• La documentation d'Azure Container Registry