Déployer un agent hébergé

Déployer avec Azure Developer CLI ou VS Code

L’interface CLI Azure développeur (azd) et la Microsoft Foundry Toolkit pour Visual Studio Code automatiser le cycle de vie de déploiement complet : création du conteneur, envoi (push) vers Azure Container Registry, création de la version de l’agent et attribution de rôles RBAC. Pour obtenir une procédure pas à pas guidée pour la première fois, consultez le guide de démarrage rapide : Créer et déployer un agent hébergé.

Déployer avec une commande

À partir de votre répertoire de projet d’agent, approvisionnez l’infrastructure et déployez en une seule étape :

azd up

azd up associe azd provision, qui crée le projet Foundry, le déploiement du modèle, le registre de conteneurs, Application Insights et l’identité managée, à azd deploy. Utilisez-le pour les déploiements de première fois ou chaque fois que vous modifiez le code de l’infrastructure et de l’agent.

Déployer les modifications de code uniquement

Si vous avez déjà provisionné vos ressources Azure et que vous n’avez besoin que d’envoyer (push) une nouvelle version de l’agent :

azd deploy

Pendant azd deploy, le CLI :

1. Génère votre image conteneur à distance dans Azure Container Registry, vous n'avez donc pas besoin de Docker local.
2. Elle envoie (push) l’image au registre.
3. Crée une version hébergée de l’agent sur Foundry Agent Service.
4. Crée une identité d’agent Microsoft Entra dédiée et affecte les rôles RBAC dont l’agent a besoin pour accéder aux modèles et outils.

Gérer les versions

Chacun azd deploy crée une nouvelle version de l’agent. L’interface CLI conserve les versions précédentes et la dernière version est active par défaut.

Vérifier le déploiement

azd ai agent show

La sortie inclut le nom de l’agent, la version, les protocoles, les ressources de conteneur, les variables d’environnement et l’horodatage de création. Utiliser --output table pour une vue récapitulative.

Générer des images localement

Par défaut, azd génère des images conteneur à distance dans Azure Container Registry. Pour générer des images localement, définissez remoteBuild: false dans azure.yaml. Les builds locales nécessitent Docker Desktop.

Pour filtrer les requêtes et les réponses conformément à une politique de sécurité du contenu, ajoutez un garde-fou de sécurité du contenu à votre agent.

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.3.0 ou ultérieure

  pip install "azure-ai-projects>=2.3.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é

Lorsque vous créez une version, la plateforme provisionne automatiquement l’agent. Il n’y a pas d’étape de début distincte. La plateforme génère un instantané de conteneur et prépare l’agent à traiter les demandes.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointProtocol,
    ContainerConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
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,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(
            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 protocol_versions:

protocol_versions=[
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS_WS, version="1.0.0"),
],

Paramètres clés :

Pour définir quand le calcul de session est inactif, consultez Gérer l’inactivité de la session.

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",
}, 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 du Kit de développement logiciel (SDK) JavaScript/TypeScript

Utilisez le Kit de développement logiciel (SDK) lorsque vous souhaitez gérer les déploiements d’agents directement à partir de Node.js code. L'appelant du Kit de développement logiciel (SDK) s'exécute dans Node.js, mais l'image conteneur elle-même exécute toujours votre code d'agent Python ou .NET généré avec les bibliothèques de protocole Réponses ou Invocations : il n'existe aucun runtime d'agent hébergé Node.js.

Prérequis supplémentaires

• Node.js 22 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)

• Les packages @azure/identity et @azure/ai-projects

  npm install @azure/ai-projects @azure/identity
  

Avant de commencer, générez et envoyez (push) votre image conteneur à Azure Container Registry (consultez l’onglet Python par exemple commandes Docker) et accordez à l’identité managée du projet le rôle Lecteur du référentiel du Registre de conteneurs sur le Registre.

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

Lorsque vous créez une version, la plateforme provisionne automatiquement l’agent. Il n’y a pas d’étape de début distincte. La plateforme génère un instantané de conteneur et prépare l’agent à traiter les demandes.

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] || "your_project_endpoint";
const agentName = "my-agent";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

// Create a hosted agent version
const agent = await project.agents.createVersion(agentName, {
  kind: "hosted",
  cpu: "1",
  memory: "2Gi",
  container_configuration: {
    image: "your-registry.azurecr.io/your-image:tag",
  },
  protocol_versions: [{ protocol: "responses", version: "1.0.0" }],
  environment_variables: { MODEL_DEPLOYMENT_NAME: "gpt-5-mini" },
});

console.log(`Agent created: ${agent.name}, version: ${agent.version}`);

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

protocol_versions: [
  { protocol: "responses", version: "1.0.0" },
  { protocol: "invocations", version: "1.0.0" },
  { protocol: "invocations_ws", version: "1.0.0" },
],

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.

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Poll until the agent version is active
for (;;) {
  const versionInfo = await project.agents.getVersion(
    agentName,
    agent.version,
  );
  console.log(`Status: ${versionInfo.status}`);
  if (versionInfo.status === "active") {
    break;
  }
  if (versionInfo.status === "failed") {
    console.log(`Provisioning failed: ${versionInfo.error}`);
    break;
  }
  await sleep(5_000);
}

Router le point de terminaison de l’agent et l’invoquer

Routez le point de terminaison de l’agent vers la version que vous avez créée, puis liez un client OpenAI au point de terminaison.

Pour le protocole Réponses :

await project.agents.patchAgentObject(agentName, {
  agentEndpoint: {
    version_selector: {
      version_selection_rules: [
        {
          type: "FixedRatio",
          agent_version: agent.version,
          traffic_percentage: 100,
        },
      ],
    },
    protocol_configuration: { responses: {} },
  },
});

// Create an OpenAI client bound to the agent endpoint
const openAIClient = project.getOpenAIClient({
  azureConfig: { allowPreview: true, agentName },
});

const response = await openAIClient.responses.create({
  input: "Hello! What can you do?",
});
console.log(response.output_text);

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

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");
if (!token) {
  throw new Error("Failed to acquire an access token.");
}
const url = `${projectEndpoint}/agents/my-agent/endpoint/protocols/invocations`;

const response = await fetch(`${url}?api-version=v1`, {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token.token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Process this task" }),
});
console.log(await response.json());

Référence : AIProjectClient

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 à Azure Container Registry, puis accordez à l’identité managée du projet le rôle Lecteur du référentiel du Registre de conteneurs sur le Registre.

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",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v1"
      },
      "cpu": "1",
      "memory": "2Gi",
      "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.

Pour définir quand le calcul de session est inactif, consultez Gérer l’inactivité de la session.

Pour analyser les requêtes et les réponses au regard d’une politique de sécurité du contenu, incluez un objet rai_config dans le definition. Consultez Ajouter un garde-fou de sécurité de contenu à un agent hébergé.

Interroger 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" \
  -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",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v2"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

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. Permet force=True de supprimer en cascade toutes les sessions actives, telles que juste après avoir appelé l’agent ; sans cela, l’appel échoue avec une erreur de conflit pendant que les sessions sont actives :

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

Nettoyage du Kit de développement logiciel (SDK

Supprimez une seule version :

await project.agents.deleteVersion("my-agent", agent.version);

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

await project.agents.delete("my-agent", { force: true });

Référence : AIProjectClient

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"