Tutoriel : Créer une application web agentique dans Azure App Service avec LangGraph ou Foundry Agent Service (Python)

Ce didacticiel montre comment ajouter une fonctionnalité agentique à une application CRUD FastAPI pilotée par les données existante. Cela utilise deux approches différentes : LangGraph et Foundry Agent Service.

Si votre application web dispose déjà de fonctionnalités utiles, telles que le shopping, la réservation d’hôtels ou la gestion des données, il est relativement simple d’ajouter des fonctionnalités d’agent à votre application web en encapsulant ces fonctionnalités dans un plug-in (pour LangGraph) ou en tant que point de terminaison OpenAPI (pour le service De l’agent Foundry). Dans ce tutoriel, vous commencez par une application de liste de tâches simple. À la fin, vous pourrez créer, mettre à jour et gérer des tâches avec un agent dans une application App Service.

LangGraph

Service de l’agent Foundry

LangGraph et Foundry Agent Service vous permettent de créer des applications web agentiques avec des fonctionnalités basées sur l’IA. LangGraph est similaire au noyau sémantique Microsoft et est un kit de développement logiciel (SDK). Le tableau suivant présente quelques-uns des points à prendre en compte et des adaptations :

Considération	LangGraph ou noyau sémantique	Service d’agent de la fonderie
Performance	Rapide (s’exécute localement)	Plus lent (service managé, distant)
Développement	Code complet, contrôle maximal	Code faible, intégration rapide
Essai	Tests manuels/unitaires dans le code	Terrain de jeu intégré pour les tests rapides
Extensibilité	Managé par l’application	Managé par Azure, mise à l’échelle automatique

Dans ce tutoriel, vous allez apprendre à :

• Convertissez les fonctionnalités d’application existantes en plug-in pour LangGraph.
• Ajoutez le plug-in à un agent LangGraph et utilisez-le dans une application web.
• Convertir les fonctionnalités de l'application existante en un point de terminaison OpenAPI pour le Service de l’Agent Foundry.
• Appelez un agent Microsoft Foundry dans une application web.

• Attribuez les autorisations requises pour la connectivité d’identité managée.

Prerequisites

• Un compte Azure avec un abonnement actif : créez gratuitement un compte.
• Compte GitHub pour utiliser GitHub Codespaces - En savoir plus sur GitHub Codespaces.

Ouvrir l’exemple avec Codespaces

Le moyen le plus simple de commencer consiste à utiliser GitHub Codespaces, qui fournit un environnement de développement complet avec tous les outils requis préinstallés.

1. Accédez au référentiel GitHub à l’adresse https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

2. Sélectionnez le bouton Code, sélectionnez l’onglet Codespaces, puis sélectionnez Créer un codespace sur l’espace principal.

3. Attendez quelques instants que votre Codespace s’initialise. Lorsqu’il est prêt, un environnement de développement entièrement configuré s’affiche dans votre navigateur.

4. Exécutez l’application localement :

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

5. Lorsque vous voyez Votre application s’exécutant sur le port 3000 est disponible, sélectionnez Ouvrir dans le navigateur et ajoutez quelques tâches.

   Les agents ne sont pas entièrement configurés, donc ils ne fonctionnent pas encore. Vous les configurerez ultérieurement.

Examinez le code de l’agent

Les deux approches utilisent le même modèle d’implémentation, où l’agent est initialisé au démarrage de l’application et répond aux messages utilisateur par des demandes POST.

LangGraph

Le LangGraphTaskAgent est initialisé dans le constructeur dans src/agents/LangGraphTaskAgent.ts. Le code d’initialisation effectue les opérations suivantes :

• Configure le client AzureChatOpenAI en utilisant des variables d’environnement.
• Crée l’agent ReAct prédéfini avec de la mémoire et un ensemble d’outils CRUD pour la gestion des tâches (consultez Guide de démarrage rapide LangGraph).

# Initialize Azure OpenAI client
credential = DefaultAzureCredential()
azure_ad_token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)

self.llm = AzureChatOpenAI(
    azure_endpoint=endpoint,
    azure_deployment=deployment_name,
    azure_ad_token_provider=azure_ad_token_provider,
    api_version="2024-10-21"
)

# Define tools
tools = [
    self._create_task_tool(),
    self._get_tasks_tool(),
    self._get_task_tool(),
    self._update_task_tool(),
    self._delete_task_tool()
]

# Create the agent
self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)
print("LangGraph Task Agent initialized successfully")

Service de l’agent Foundry

Le FoundryTaskAgent est initialisé dans le constructeur de src/agents/foundry_task_agent.py. Le code d’initialisation effectue les opérations suivantes :

• Crée un AIProjectClient en utilisant les identifiants Azure.
• Récupère l’agent à partir de Microsoft Foundry par l’ID de l’agent.
• Crée un thread pour la session.

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)
self.agent_id = agent_id

# Create a thread for this session
thread = self.project_client.agents.threads.create()
self.thread_id = thread.id

Ce code d’initialisation ne définit aucune fonctionnalité pour l’agent, car vous générez généralement l’agent dans le portail Foundry. Dans le cadre de l’exemple de scénario, il suit également le modèle OpenAPI présenté dans Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Python) et rend ses fonctionnalités CRUD disponibles en tant que point de terminaison OpenAPI. Cela vous permet de l’ajouter à l’agent ultérieurement en tant qu’outil que vous pouvez appeler.

Le code OpenAPI est défini dans src/routes/api.py. Par exemple, l’itinéraire « GET /tasks » définit un paramètre personnalisé operation_id , tel que requis par l’outil de spécification OpenAPI dans Microsoft Foundry, et description aide l’agent à déterminer comment appeler l’API :

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

Déployer l’exemple d’application

L’exemple de référentiel contient un modèle Azure Developer CLI (AZD), qui crée une application App Service avec une identité managée et déploie votre exemple d’application.

1. Dans le terminal, connectez-vous à Azure à l’aide d’Azure Developer CLI :

   azd auth login
   

   Suivez les instructions pour terminer le processus d’authentification.

2. Déployez l’application Azure App Service avec le modèle AZD :

   azd up
   

3. Lorsque vous y êtes invité, fournissez les réponses suivantes :

   Question	Réponse
   Entrez un nom pour le nouvel environnement :	Tapez un nom unique.
   Sélectionnez un abonnement Azure à utiliser :	Sélectionnez l’abonnement.
   Choisissez un groupe de ressources à utiliser :	Sélectionnez Créer un groupe de ressources.
   Sélectionnez un emplacement dans lequel créer le groupe de ressources :	Sélectionnez une région. Les ressources seront en fait créées dans USA Est 2.
   Entrez un nom pour le nouveau groupe de ressources :	Tapez Entrée.

4. Dans la sortie AZD, retrouvez l’URL de votre application et accédez-y dans le navigateur. L’URL ressemble à ceci dans la sortie AZD :

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
    

5. Sélectionnez l’élément Schéma OpenAPI pour ouvrir le schéma OpenAPI généré automatiquement au chemin d’accès /openapi.json par défaut. Vous aurez besoin de ce schéma plus tard.

6. Une fois le déploiement réussi, vous verrez une URL pour votre application déployée.

   Vous disposez maintenant d’une application App Service avec une identité managée affectée par le système.

Créer et configurer la ressource Microsoft Foundry

1. Dans le portail Foundry, déployez un modèle de votre choix (consultez Démarrage rapide : Prise en main de Microsoft Foundry). Un projet et un agent par défaut sont créés pour vous dans le processus.

2. Dans le menu de gauche, sélectionnez Vue d’ensemble.

3. Sélectionnez Microsoft Foundry et copiez l’URL dans le point de terminaison du projet Microsoft Foundry.

4. Sélectionnez Azure OpenAI et copiez l’URL dans le Point de terminaison Azure OpenAI pour plus tard.

   

5. Dans le menu de gauche, sélectionnez Agents, puis sélectionnez l’agent par défaut.

6. Dans le volet Installation, copiez l’ID d’agent, ainsi que le nom du modèle dans Déploiement.

   

7. Dans le volet Installation, ajoutez une action avec l’outil de spécification OpenAPI. Utilisez le schéma OpenAPI obtenu à partir de l’application web déployée et de l’authentification anonyme. Pour obtenir des instructions détaillées, consultez Comment utiliser l’outil de spécification OpenAPI.

   Votre code d’application est déjà configuré pour inclure url et operationId du serveur qui sont nécessaires pour l’agent. Pour plus d’informations, consultez How to use Foundry Agent Service with OpenAPI Specified Tools : Prerequisites.

8. Sélectionnez Essayer dans le terrain de jeu et testez votre agent Foundry avec des invites telles que « Montre-moi toutes les tâches ».

   Si vous obtenez une réponse valide, l’agent effectue des appels d’outils au point de terminaison OpenAPI sur votre application web déployée.

Attribuer les autorisations nécessaires

1. Dans le coin supérieur droit du portail de Foundry, sélectionnez le nom de la ressource, puis sélectionnez Groupe de ressources pour l’ouvrir dans le Portail Azure.

   

2. Ajoutez un rôle pour chacune des deux ressources pour l’identité de gestion de l’application App Service à l’aide du tableau suivant :

   Ressource cible	Rôle requis	Nécessaire pour
   Microsoft Foundry	Utilisateur OpenAI de Cognitive Services	Service de saisie semi-automatique de conversation dans le LangGraph.
   Projet Microsoft Foundry	Utilisateur Azure AI	Lecture et appel de l’agent Foundry.

   Pour obtenir des instructions, consultez Attribuer des rôles Azure à l’aide du portail Azure.

Configurer des variables de connexion dans votre exemple d’application

1. Ouvrez .env. À l’aide des valeurs que vous avez copiées précédemment à partir du portail Foundry, configurez les variables suivantes :

   Variable	Descriptif
   AZURE_OPENAI_ENDPOINT	Point de terminaison Azure OpenAI (copié à partir de la page de présentation). Cela est nécessaire pour l’agent LangGraph.
   AZURE_OPENAI_DEPLOYMENT_NAME	Nom du modèle dans le déploiement (copié à partir du volet Configuration des agents). Cela est nécessaire pour l’agent LangGraph.
   AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Point de terminaison du projet Microsoft Foundry (copié à partir de la page Vue d’ensemble). Ceci est nécessaire pour le Service de l’agent Foundry.
   AZURE_AI_FOUNDRY_AGENT_ID	ID de l’agent (copié à partir du volet d’installation des agents). Cela est nécessaire pour appeler un agent Microsoft Foundry existant.

   Note

   Pour simplifier le tutoriel, vous allez utiliser ces variables dans .env au lieu de les remplacer par des paramètres d’application dans App Service.

2. Se connecter à Azure avec Azure CLI :

   az login
   

   Cela permet à la bibliothèque cliente Azure Identity dans l’exemple de code de recevoir un jeton d’authentification pour l’utilisateur connecté. N’oubliez pas que vous avez ajouté le rôle requis pour cet utilisateur précédemment.

3. Exécutez l’application localement :

   npm run build
   npm start
   

4. Lorsque vous voyez Votre application s’exécutant sur le port 3000 est disponible, sélectionnez Ouvrir dans le navigateur.

5. Sélectionnez le lien Agent LangGraph et le lien Agent Foundry pour essayer l’interface de conversation. Si vous obtenez une réponse, votre application se connecte correctement à la ressource Microsoft Foundry.

6. De retour dans le codespace GitHub, déployez les modifications apportées à votre application.

   azd up
   

7. Accédez à nouveau à l’application déployée et testez les agents de conversation.

LangGraph

Service de l’agent Foundry

Nettoyer les ressources

Lorsque vous avez terminé avec l’application, vous pouvez supprimer les ressources App Service afin d’éviter des coûts supplémentaires :

azd down --purge

Étant donné que le modèle AZD n’inclut pas les ressources Microsoft Foundry, vous devez les supprimer manuellement si vous le souhaitez.

Plus de ressources

• Intégrer l’IA à vos applications Azure App Service
• Qu’est-ce que le Service de l’agent Foundry ?
• LangGraph - Démarrage rapide