Déployer un agent hébergé à partir du code source

Cet article explique comment déployer un agent hébergé dans Foundry Agent Service à partir de code source Python ou .NET, sans créer ni publier une image de conteneur. Vous chargez un .zip code (et éventuellement vos dépendances) et le service Agent l’exécute as-is ou génère vos dépendances pour vous dans le cloud.

Tip

Pour la plupart des scénarios, déployez avec Azure Developer CLI (azd) ou le Foundry Toolkit pour VS Code. Ces outils effectuent le gros travail pour vous : ils empaquetent votre source, le chargent, interrogent activeet configurent automatiquement le contrôle d’accès en fonction du rôle. Pour commencer, suivez le guide de démarrage rapide : Déployez votre premier agent hébergé et choisissez Code (ou Code source (chargement ZIP)) lorsque vous êtes invité à entrer une méthode de déploiement.

Utilisez le Kit de développement logiciel (SDK) et les procédures REST de cet article lorsque vous devez déployer des agents de code source par programmation, à partir du SDK Python ou du SDK .NET dans vos propres applications, ou directement via l’API REST pour l’automatisation personnalisée, l’automatisation indépendante du langage ou l’intégration à des systèmes de livraison continue existants. Dans cet article, vous allez effectuer les tâches suivantes :

  • Choisissez un mode de résolution de dépendances et empaquetez votre source.
  • Créez l’agent, attendez qu’il atteigne active, puis appelez-le.
  • Mettre à jour, gérer les versions, télécharger et diffuser les journaux en continu de l’assistant déployé.

Si vous avez besoin d’un contrôle total de l’image runtime ou que vous disposez déjà d’un fichier Dockerfile opérationnel, utilisez le chemin d’accès basé sur le conteneur : déployer un agent hébergé.

Si vous utilisez un assistant de codage comme GitHub Copilot pour empaqueter et déployer votre code source, le Microsoft Foundry Skill peut vous aider à préparer votre projet et à suivre les étapes requises avec azd, le SDK ou l’API REST.

Prerequisites

  • Un projet Microsoft Foundry dans une région prise en charge.
  • Azure CLI version 2.80 ou ultérieure, connecté au locataire propriétaire du projet.

  • pip de Python 3.13 ou version ultérieure, pour empaqueter votre source localement.

  • La version azure-ai-projects 2.2.0 ou ultérieure et les paquets azure-identity.

    pip install "azure-ai-projects>=2.2.0" azure-identity

Environnements d’exécution pris en charge

Le code_configuration.runtime champ de la définition de l’agent accepte les valeurs suivantes. Choisissez le runtime qui correspond aux fichiers binaires de votre fichier zip : les wheels de x86_64 Linux pour Python, ou la valeur TargetFramework de votre sortie dotnet publish pour .NET.

Language Valeurs du runtime
Python python_3_13, python_3_14
.NET dotnet_10

Stratégie de prise en charge des versions linguistiques

L’environnement d’exécution du service d’agent inclut l’image de conteneur générée par la plateforme pour chaque valeur de code_configuration.runtime. Pour que vos agents déployés soient entièrement pris en charge, Foundry aligne la prise en charge du langage de l’agent hébergé avec la prise en charge de la fin de vie de chaque langue. La prise en charge se termine à la date de fin de prise en charge de la communauté pour la version linguistique. Microsoft peut mettre hors service une valeur code_configuration.runtime plus tôt lorsque les contraintes de plateforme (telles que l’image de base sous-jacente) l’exigent.

Pour connaître les planifications de fin de support en amont, consultez :

Phase de mise hors service

Après une date de fin de vie du langage, vous pouvez toujours créer, mettre à jour et exécuter des agents hébergés qui utilisent la valeur d’exécution supprimée. Toutefois, ces agents ne sont pas éligibles pour la prise en charge, les nouvelles fonctionnalités ou les correctifs de sécurité tant que vous ne les mettez pas à niveau vers un runtime pris en charge en définissant une valeur actuelle code_configuration.runtime et en redéployant.

Autorisations requises

Vous avez besoin du rôle Foundry Project Manager au niveau du projet pour déployer un agent hébergé. Ce rôle accorde les autorisations de plan de données pour créer et mettre à jour des agents, ainsi que la possibilité de créer des attributions de rôles pour l’identité de l’agent créé par la plateforme si nécessaire. Pour obtenir une répartition détaillée des autorisations impliquées, consultez la référence des autorisations de l’agent hébergé.

Important

Les rôles Foundry RBAC ont été récemment renommés. Foundry User, Foundry Owner, Propriétaire du compteFoundry et Foundry Project Manager ont été précédemment nommés Azure utilisateur IA, Azure propriétaire d’IA, propriétaire Azure compte IA et Azure gestionnaire Project IA. Il se peut que vous voyiez encore les anciens noms à certains endroits pendant le déploiement de ce changement de nom. Les ID de rôle et les autorisations de base ne sont pas modifiés par ce changement de nom.

Votre agent s’exécute en tant qu’identité managée affectée par la plateforme qui est distincte de votre identité utilisateur. Cette identité peut accéder à l’inférence du modèle via le point de terminaison du projet et le stockage de session par défaut. Pour les ressources externes (par exemple, votre propre stockage Azure), attribuez manuellement des rôles RBAC aux Microsoft Entra ID de l'agent. Pour plus d’informations, consultez l’accès agent au-delà des valeurs par défaut.

Cycle de vie du déploiement

Chaque déploiement de code source suit la même séquence : package -> créer ou mettre à jour -> interroger jusqu’à active -> appeler. Le chemin d’accès au code source utilise code_configuration dans la définition de l’agent. Le chemin d’accès basé sur l’image utilise container_configuration à la place. Ces deux options s’excluent mutuellement sur une seule version.

Choisissez le chemin qui correspond à votre flux de travail. Si vous n'êtes pas sûr, commencez par l'interface CLI Azure développeur ou VS Code. Il s'agit du chemin recommandé pour la plupart des clients.

Chemin Idéal pour Emballage
Azure Developer CLI ou VS Code La plupart des déploiements, y compris les premiers déploiements et la boucle interne la plus rapide. L’outil génère et charge le fichier zip pour vous.
Kit de développement logiciel (SDK) Python Déploiement par programmation à partir d’applications Python ou d’automatisation. Vous générez le zip ; le Kit de développement logiciel (SDK) le charge.
Kit de développement logiciel (SDK) .NET Déploiement par programmation à partir d’applications .NET ou d’automatisation. Le Kit de développement logiciel (SDK) compresse un dossier pour vous.
Kit de développement logiciel (SDK) JavaScript/TypeScript Déploiement par programmation à partir d’applications Node.js ou d’automatisation. Déploie Python ou .NET source ; il n'existe aucun runtime hébergé Node.js. Vous générez le zip ; le Kit de développement logiciel (SDK) le charge.
REST API Outils personnalisés, automatisation indépendante du langage et systèmes CD. Vous générez le fichier zip et envoyez la requête multipart.

Choisir la façon dont les dépendances sont résolues

Avant de commencer, choisissez une valeur pour code_configuration.dependency_resolution. Ce choix affecte ce que vous mettez dans le fichier ZIP.

Valeur Behavior À utiliser lorsque
remote_build Agent Service installe des dépendances à partir de requirements.txt (Python) ou restaure le fichier projet (.NET) pendant l’approvisionnement. Vous souhaitez un petit chargement et la boucle interne la plus simple. Recommandé pour les utilisateurs de première fois.
bundled L’archive ZIP est exécutée telle quelle. Vous incluez des dépendances Linux précompilées dans packages/ (Python) ou dans la sortie dotnet publish (.NET). Vous avez besoin de builds reproductibles, vos dépendances sont privées ou uniquement disponibles sous forme de wheels, ou votre projet ne se restaure pas correctement côté serveur.

Pour le mode groupé, consultez Packager manuellement le fichier zip pour les commandes de build locales.

Exigences de pare-feu pour les réseaux virtuels privés

Si vous sécurisez votre projet avec un réseau virtuel privé, mettez à jour votre stratégie réseau pour autoriser les connexions sortantes aux points de terminaison suivants avant de déployer.

Tous les déploiements de code source nécessitent un accès sortant à :

  • mcr.microsoft.com
  • *.login.microsoft.com

Pour la configuration réseau, consultez Déployer un agent hébergé dans un réseau virtuel.

Déployer à l’aide d’Azure Developer CLI ou de VS Code

L’interface de ligne de commande Azure Developer (azd) et le Foundry Toolkit pour VS Code automatisent l’ensemble du cycle de vie du déploiement du code source : ils empaquettent votre code source dans un fichier ZIP, calculent le hachage SHA-256, le téléversent, surveillent active et configurent pour vous le contrôle d’accès basé sur les rôles. Ces outils sont le chemin recommandé pour la plupart des clients et la boucle interne la plus rapide.

Pour obtenir une procédure pas à pas, consultez le guide de démarrage rapide : Déployer votre premier agent hébergé. Choisissez Code (ou Code source (chargement ZIP)) lorsque le démarrage rapide demande une méthode de déploiement.

Sélectionner le déploiement de code source

Lorsque vous exécutez azd ai agent init de manière interactive, l’outil vous invite à choisir un mode de déploiement. Choisissez le code à déployer à partir de la source en tant que chargement ZIP au lieu de créer une image conteneur. Le déploiement de code est le mode par défaut pour Python et les agents hébergés .NET. La boîte à outils Foundry pour VS Code vous demande la méthode de déploiement de la même manière.

Pour sélectionner le déploiement de code source de manière non interactive, par exemple, dans un pipeline CI/CD, passez --deploy-mode code. Ce mode nécessite --runtime et --entry-pointaccepte une valeur facultative --dep-resolution ( remote_build par défaut) ou bundled:

azd ai agent init --no-prompt --project-id "<project-resource-id>" \
  --deploy-mode code --runtime python_3_13 --entry-point main.py

Après l’initialisation, azd écrit les paramètres de déploiement de code source dans le codeConfigurationazure.ai.agent champ du service dans azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint:
        - python
        - main.py
      dependencyResolution: remote_build

Exécutez azd up pour provisionner et déployer. Utilisez --deploy-mode container uniquement lorsque vous souhaitez générer ou référencer une image conteneur à la place.

Utilisez les chemins d’accès SDK ou REST dans les sections suivantes lorsque vous devez déployer par programmation à partir de votre propre application ou intégrer des outils existants.

Déployer à partir de code source

Sélectionnez votre langue ou votre interface. Chaque onglet traverse le même cycle de vie : créez l’agent, interrogez jusqu’à atteindre active, appelez-le et téléchargez le code déployé.

Utilisez le sdk Python pour déployer des agents de code source à partir de vos propres applications ou automatisation. Vous générez le zip vous-même et transmettez ses octets et SHA-256 au Kit de développement logiciel (SDK), qui le charge et expose les mêmes opérations de création, d’interrogation, d’appel et de téléchargement que l’API REST. Le déploiement du code nécessite azure-ai-projects version 2.2.0 ou ultérieure.

Générer le fichier zip

Le sdk Python charge un fichier zip que vous générez. Utilisez les mêmes règles de disposition et de résolution de dépendances décrites dans Packager manuellement le fichier zip. La charge utile minimale remote_build est un zip plat avec main.py et requirements.txt à la racine.

Créer l’agent

import hashlib
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")

code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

created = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="1.0.0")
        ],
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini"},
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hello-world code agent",
)
print(f"Created version: {created.version}")

Pour le protocole Invocations, définissez l’entrée protocol_versions sur ProtocolVersionRecord(protocol="invocations", version="1.0.0"). Pour le protocole Invocations (WebSocket), utilisez ProtocolVersionRecord(protocol="invocations_ws", version="1.0.0"). Pour le mode bundled, définissez dependency_resolution="bundled" et incluez des dépendances précompilées dans l’archive ZIP. Pour plus d’informations, consultez Générer des dépendances Linux localement.

Vérifier l’état actif

import time

while True:
    version = project.agents.get_version(
        agent_name=AGENT_NAME, agent_version=created.version
    )
    status = version["status"]
    print(f"Status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Provisioning failed: {version.get('error')}")
    time.sleep(5)

Consultez Poll for active pour obtenir la liste complète des valeurs d’état et la façon de lire l’objet error en cas d’échec.

Appeler l’agent

Une fois la version atteinte active, liez un client OpenAI au point de terminaison de l’agent et appelez-le. Cet exemple utilise le protocole Réponses :

openai_client = project.get_openai_client(agent_name=AGENT_NAME)

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 Invoke avec un jeton Bearer, comme illustré dans Appeler l’agent.

Télécharger le fichier zip déployé

Vérifiez exactement ce qui est déployé en téléchargeant le fichier zip et en comparant sa sha-256 à la valeur que vous avez chargée :

import hashlib
from pathlib import Path

out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
    for chunk in project.agents.download_code(
        agent_name=AGENT_NAME, agent_version=created.version
    ):
        f.write(chunk)
        sha.update(chunk)

print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")

Pour obtenir un exemple exécutable complet, consultez les exemples Python hosted-agent.

Empaqueter le zip manuellement

Si vous utilisez azd, ignorez cette section :azd génère le zip pour vous. Lisez-la si vous utilisez l’API REST, si vous basculez vers la résolution de dépendance groupée , ou si vous avez besoin d’un contrôle total sur le contenu du chargement.

Le fichier zip doit être plat à la racine, sans dossier wrapper de niveau supérieur.

Sélectionnez l’onglet pour la langue de votre agent.

configuration Python (mode de compilation à distance)

Le service installe les dépendances dans le cloud à partir de requirements.txt.

agent-code.zip
+-- main.py
+-- requirements.txt

Disposition Python (mode intégré)

Vous expédiez des dépendances Linux prédéfinies dans packages/.

agent-code.zip
+-- main.py                    # entry point
+-- requirements.txt
+-- packages/                  # extracted modules (not raw .whl files)
    +-- azure/identity/__init__.py
    +-- requests/__init__.py

Générer des dépendances Linux localement (groupées, Python)

Utilisez la balise de plateforme manylinux2014_x86_64 pour que pip télécharge des wheels Linux, même depuis Windows ou macOS.

Bash

pip install -r requirements.txt \
    --target packages/ \
    --platform manylinux2014_x86_64 \
    --python-version 3.13 \
    --implementation cp \
    --only-binary=:all:

zip -r agent-code.zip main.py requirements.txt packages/

PowerShell / Windows cmd

pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:

tar -a -c -f agent-code.zip main.py requirements.txt packages

--only-binary=:all: impose l’utilisation de wheels (aucune génération à partir du code source). La valeur de --python-version doit correspondre à la valeur runtime dans la définition de l’agent.

Warning

Erreurs courantes d’empaquetage qui provoquent session_creation_failed ou ModuleNotFoundError:

  • Placer la source dans un dossier (my-agent/main.py au lieu de main.py à la racine).
  • Inclure des fichiers bruts dans .whl au lieu de modules extraits packages/.
  • Regroupement de fichiers binaires Windows (.pyd, .dll) pour un runtime Linux.

Limites

Limite Valeur
Taille zip maximale (chargement multipart) 250 Mo

Pour connaître les combinaisons cpu et memory prises en charge, consultez Tailles du bac à sable.

Troubleshooting

Symptôme Cause la plus probable Réparer
401 Unauthorized Jeton manquant ou de portée incorrecte Acquérir un jeton avec --resource https://ai.azure.com.
403 Forbidden L’appelant ne dispose pas du contrôle d’accès basé sur les rôles pour ce projet Accordez les droits Foundry Agent Consumer (pour les appels uniquement) ou Foundry User (pour également développer) à l’échelle du projet.
409 conflict sur Créer (Agent '<name>' already exists) Le nom de l’agent existe déjà Utilisez Update (POST /agents/{name}) ou choisissez un nouveau nom.
400 bad_request (CPU and Memory must be specified as a valid resource tier) lors de la création ou de la mise à jour cpu / memory ne sont pas l’un des niveaux pris en charge Définissez cpu et memory sur une paire valide parmi les Configurations d’environnement de test.
400 bad_request (Agent version is still being provisioned) lors de l’invocation Une nouvelle version est en cours de déploiement et la version active est en cours de remplacement Interrogez la version status jusqu’à active, puis réessayez.
424 session_not_ready à l’invocation Le conteneur a démarré mais /readiness n’a pas retourné HTTP 200 dans le délai d’expiration Diffusez les journaux en continu avec :logstream, corrigez la sonde de préparation ou l’erreur de démarrage, puis redéployez.
409 conflict sur l’assistant DELETE (Agent has active sessions) Les sessions ouvertes bloquent la suppression Attendez que les sessions deviennent inactives, ou ajoutez &force=true pour supprimer les sessions en cascade.
Version bloquée dans creating (>10 min, compilation à distance) Échec de la génération côté serveur ou résolution impossible requirements.txt Passez à dependency_resolution: bundled et effectuez une précompilation en local.
Le déploiement échoue dans un réseau virtuel privé Les points de terminaison sortants requis sont bloqués par le pare-feu Autorisez les points de terminaison dans les exigences du pare-feu pour les réseaux virtuels privés, puis redéployez.
Transitions de version vers failed Mauvaise disposition zip, erreur de syntaxe ou (remote_build) échec de restauration/compilation Lisez d'abord l'objet error de la version : error.code classifie l'échec et error.message contient la ligne d'erreur de restauration ou de compilation sous-jacente (pip pour Python, NuGet pour .NET) ainsi qu'un lien de résolution des problèmes. Vérifiez la structure du dossier. Utilisez :logstream uniquement une fois le conteneur démarré.
ModuleNotFoundError au moment de l’exécution packages/ manquant, contient des fichiers .whl bruts ou contient des fichiers binaires Windows Reconstruire avec pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased lors du téléchargement L’agent fonctionne à partir d’images Utilisez le document de déploiement basé sur un conteneur.

Nettoyer les ressources

Si vous avez généré une structure du projet à partir du démarrage rapide avec azd, exécutez azd down à partir de la racine du projet pour supprimer l’ensemble de l’environnement provisionné.

Pour supprimer un agent que vous avez déployé avec le Kit de développement logiciel (SDK) ou l’API REST, utilisez le chemin correspondant ci-dessous.

# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)

# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)

Warning

La suppression d’un agent supprime toutes ses versions et met fin à des sessions actives. Cette action ne peut pas être annulée.

Étapes suivantes

Gérer le cycle de vie de l’agent hébergé

Contenu connexe

  • Last updated on