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 guide de démarrage rapide utilise l’interface CLI Azure Developer CLI (azd) ou VS Code extension, qui gère automatiquement la génération, l’envoi de 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 de l’agent : enregistrez l’image auprès du service d’agent Foundry. La plateforme provisionne l’infrastructure et crée une identité d’agent Entra dédiée.
3. Interroger l’état : patientez jusqu’à ce 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 d'agent utilisant un framework 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 de Azure AI Project Manager à l'étendue 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 doit être Azure AI User sur le projet pour accéder aux modèles et artefacts à l'exécution.

Si vous utilisez azd ou l’extension VS Code, l’outil gère 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é de l’agent créé par la plateforme (modèle d'exécution en temps réel et pour accéder aux outils)

Pour plus d’informations, consultez Authentification et autorisation.

Exigences des 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é.

Bibliothèque de protocole de réponses

Les bibliothèques Python et .NET pour le protocole Réponses implémentent l’API réponses IA Azure. Importez le package et implémentez l’interface IResponseHandler . La bibliothèque gère le routage, la diffusion en continu avec des événements envoyés par le serveur (SSE), l’exécution en arrière-plan, l’annulation, la mise en cache et la gestion du cycle de vie des réponses.

IResponseHandler

IResponseHandler est l’abstraction principale que vous implémentez. La bibliothèque appelle CreateAsync pour chaque requête entrante et envoie le IAsyncEnumerable<ResponseStreamEvent> retourné aux clients via SSE :

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream gère sequenceNumber, outputIndex, contentIndex, itemId et le cycle de vie complet de Response automatiquement. Chacun yield return correspond de manière unique à un événement SSE, vous n’avez donc pas besoin de suivre l'état par vous-même.

Modes de streaming et d’arrière-plan

• Mode de diffusion en continu (par défaut) : les événements SSE sont remis en temps réel au client connecté.
• Mode d’arrière-plan : le gestionnaire s’exécute jusqu’à la fin sans client SSE connecté. Les événements sont mis en mémoire tampon et disponibles pour la relecture via GET /responses/{id}.

Cycle de vie de la réponse

La bibliothèque orchestre le cycle de vie de réponse complet : created → → in_progresscompleted (ou failedcancelled). La bibliothèque gère également automatiquement l’annulation, la gestion des erreurs et les garanties d’événements terminaux.

Sécurité des threads

Toutes les instances de service inscrites via AddResponsesServer() sont sûres pour les threads. Les instances de gestionnaire sont délimitées par requête.

Pour obtenir des instructions détaillées sur l’implémentation du gestionnaire, consultez le guide d’implémentation de gestionnaire handler. Pour obtenir des exemples exécutables, consultez les exemples de protocole Responses.

Points de terminaison de santé

Les bibliothèques de protocole exposent automatiquement un /readiness point de terminaison 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 FOUNDRY_* préfixe est réservé à l’utilisation de la plate-forme.

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, telles que MODEL_DEPLOYMENT_NAME ou les points de terminaison MCP de la boîte à outils, se mettent dans la environment_variables section de agent.yaml ou l'appel du SDK (Kit de développement logiciel 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 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éployer avec Azure Developer CLI ou VS 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édacteur de référentiel de registre de conteneurs ou rôle AcrPush dans 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 envoyer (push) votre image 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. Envoyer (push) à 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 le statut de la version

Après avoir créé une version, interrogez jusqu’à ce que l’état soit active avant d’appeler 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.

Vérifier l’état de la version

Sondez 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. Le calcul de l’agent est déprovisionné après 15 minutes d’inactivité. Il n’y a donc aucun coût lorsqu’un agent ne sert pas de demandes.

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
• documentation Azure Container Registry