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

Ce tutoriel montre comment ajouter une fonctionnalité agentique à une application CRUD basée sur les données existante Express.js. 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 to-do 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

Capture d’écran d’une session de chat avec un agent LangGraph.

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 SDK, mais le noyau sémantique ne prend pas en charge JavaScript actuellement. Le tableau suivant présente certaines considérations et compromis :

Consideration	LangGraph	Service d’agent de la fonderie
Performance	Rapide (s’exécute localement)	Plus lent (service géré, distant)
Development	Code complet, contrôle maximal	Faible code, intégration rapide
Testing	Tests manuels/unitaires dans le code	Terrain de jeu intégré pour les tests rapides
Scalability	Géré par l’application	Géré 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 un compte gratuitement.
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.

Accédez au dépôt GitHub à l’adresse https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-node.
Sélectionnez le bouton Code , sélectionnez l’onglet Espaces de code, puis sélectionnez Créer un espace de code dans l’espace de code principal.
Attendez quelques instants pour que votre espace de code s’initialise. Une fois prêt, vous verrez un environnement de développement entièrement configuré dans votre navigateur.
Exécutez l’application localement :
```
npm install
npm run build
npm start
```
Lorsque vous voyez que votre application s’exécute sur le port 3000 et 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.

Passer en revue 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 requêtes POST.

LangGraph
Service de l’agent Foundry

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

Configure le client AzureChatOpenAI à l’aide de variables d’environnement.
Crée l’agent ReAct prédéfini avec un ensemble d’outils CRUD pour la gestion des tâches (voir LangGraph : comment utiliser l’agent ReAct prédéfini).
Configure la gestion de la mémoire (voir LangGraph : Ajout de la mémoire à l’agent ReAct prédéfini).

    constructor(taskService: TaskService) {
        this.taskService = taskService;
        this.memory = new MemorySaver();
        try {
            const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
            const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME;

            if (!endpoint || !deploymentName) {
                console.warn('Azure OpenAI configuration missing for LangGraph agent');
                return;
            }
            // Initialize Azure OpenAI client
            const credential = new DefaultAzureCredential();
            const azureADTokenProvider = getBearerTokenProvider(credential, "https://cognitiveservices.azure.com/.default");
            
            this.llm = new AzureChatOpenAI({
                azureOpenAIEndpoint: endpoint,
                azureOpenAIApiDeploymentName: deploymentName,
                azureADTokenProvider: azureADTokenProvider,
                azureOpenAIApiVersion: "2024-10-21"
            });
            // Define tools directly in the array
            const tools = [
                tool(
                    async ({ title, isComplete = false }) => {
                        const task = await this.taskService.addTask(title, isComplete);
                        return `Task created successfully: "${task.title}" (ID: ${task.id})`;
                    },
                    {
                        name: 'createTask',
                        description: 'Create a new task',
                        schema: z.object({
                            title: z.string(),
                            isComplete: z.boolean().optional()
                        }) as any
                    }
                ),
                tool(
                    async () => {
                        const tasks = await this.taskService.getAllTasks();
                        if (tasks.length === 0) {
                            return 'No tasks found.';
                        }
                        return `Found ${tasks.length} tasks:\n` + 
                               tasks.map(t => `- ${t.id}: ${t.title} (${t.isComplete ? 'Complete' : 'Incomplete'})`).join('\n');
                    },
                    {
                        name: 'getTasks',
                        description: 'Get all tasks',
                        schema: z.object({}) as any
                    }
                ),
                tool(
                    async ({ id }) => {
                        const task = await this.taskService.getTaskById(id);
                        if (!task) {
                            return `Task with ID ${id} not found.`;
                        }
                        return `Task ${task.id}: "${task.title}" - Status: ${task.isComplete ? 'Complete' : 'Incomplete'}`;
                    },
                    {
                        name: 'getTask',
                        description: 'Get a specific task by ID',
                        schema: z.object({
                            id: z.number()
                        }) as any
                    }
                ),
                tool(
                    async ({ id, title, isComplete }) => {
                        const updated = await this.taskService.updateTask(id, title, isComplete);
                        if (!updated) {
                            return `Task with ID ${id} not found.`;
                        }
                        return `Task ${id} updated successfully.`;
                    },
                    {
                        name: 'updateTask',
                        description: 'Update an existing task',
                        schema: z.object({
                            id: z.number(),
                            title: z.string().optional(),
                            isComplete: z.boolean().optional()
                        }) as any
                    }
                ),
                tool(
                    async ({ id }) => {
                        const deleted = await this.taskService.deleteTask(id);
                        if (!deleted) {
                            return `Task with ID ${id} not found.`;
                        }
                        return `Task ${id} deleted successfully.`;
                    },
                    {
                        name: 'deleteTask',
                        description: 'Delete a task',
                        schema: z.object({
                            id: z.number()
                        }) as any
                    }
                )
            ];

            // Create the ReAct agent with memory
            this.agent = createReactAgent({
                llm: this.llm,
                tools,
                checkpointSaver: this.memory,
                stateModifier: `You are an AI assistant that manages tasks using CRUD operations.
                
You have access to tools for creating, reading, updating, and deleting tasks.
Always use the appropriate tool for any task management request.
Be helpful and provide clear responses about the actions you take.

If you need more information to complete a request, ask the user for it.`
            });
        } catch (error) {
            console.error('Error initializing LangGraph agent:', error);
        }
    }

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

Crée un AgentsClient à l’aide des informations d’identification Azure.
Récupère l’agent à partir de Microsoft Foundry par l’ID de l’agent.
Crée un nouveau thread pour la session.

constructor(taskService: TaskService) {
    this.taskService = taskService;
    
    // Initialize the agent directly in constructor
    const endpoint = process.env.AZURE_AI_FOUNDRY_PROJECT_ENDPOINT;
    const agentId = process.env.AZURE_AI_FOUNDRY_AGENT_ID;

    if (!endpoint || !agentId) {
        console.warn('Azure AI Foundry configuration missing. Set AZURE_AI_FOUNDRY_PROJECT_ENDPOINT and AZURE_AI_FOUNDRY_AGENT_ID');
        return;
    }

    try {
        // Create the client using Azure credentials
        this.client = new AgentsClient(endpoint, new DefaultAzureCredential());
        
        // Get the agent from Azure AI Foundry, then create thread
        this.client.getAgent(agentId).then((agent) => {
            this.agentId = agent.id;
            
            // Create a new thread for this session
            return this.client!.threads.create();
        }).then((thread) => {
            this.threadId = thread.id;
            console.log(`Foundry agent initialized with ID: ${this.agentId}, Thread: ${this.threadId}`);
        }).catch((error) => {
            console.error('Error initializing Foundry agent or creating thread:', error);
        });
        
    } catch (error) {
        console.error('Error initializing Foundry agent:', error);
    }
}

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 (Node.js), 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.ts. Par exemple, l’itinéraire « GET /api/tasks » définit operationId dans les commentaires JSDoc Swagger, comme requis par l’outil de spécification OpenAPI dans Microsoft Foundry, et description aide l’agent à déterminer comment appeler l’API :

            },
            apis: ['./src/routes/*.ts'],
        });
        res.json(schema);
    } catch (error: any) {
        res.status(500).json({ error: error.message });
    }
});

/**
 * @swagger

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.

Dans le terminal, connectez-vous à Azure à l’aide d’Azure Developer CLI :
```
azd auth login
```
Suivez les instructions pour terminer le processus d’authentification.
Déployez l’application Azure App Service avec le modèle AZD :
```
azd up
```

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

Question	Answer
Entrez un nouveau nom d’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 n’importe quelle région. Les ressources seront effectivement créées dans East US 2.
Entrez un nom pour le nouveau groupe de ressources :	Tapez Entrée.

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>
 
```
Sélectionnez l’élément de schéma OpenAPI pour ouvrir le schéma OpenAPI généré automatiquement au chemin d’accès par défaut /api/schema . Vous avez besoin de ce schéma ultérieurement.
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

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.
Dans le menu de gauche, sélectionnez Vue d’ensemble.
Sélectionnez Microsoft Foundry et copiez l’URL dans le point de terminaison du projet Microsoft Foundry.
Sélectionnez Azure OpenAI et copiez l’URL dans le point de terminaison Azure OpenAI pour plus tard.
Dans le menu de gauche, sélectionnez Agents, puis sélectionnez l’agent par défaut.
Dans le volet Installation , copiez l’ID de l’agent, ainsi que le nom du modèle dans Déploiement.
Dans le volet Installation , ajoutez une action avec l’outil de spécification OpenAPI. Utilisez le schéma OpenAPI que vous obtenez à 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.
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’outil au point de terminaison OpenAPI sur votre application web déployée.

Attribuer des autorisations requises

En haut à droite du portail de recherche, sélectionnez le nom de la ressource, puis sélectionnez Groupe de ressources pour l’ouvrir dans le portail Azure.

Ajoutez un rôle pour chacune des deux ressources de 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 d’achèvement de conversation dans 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

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

Variable	Description
`AZURE_OPENAI_ENDPOINT`	Point de terminaison Azure OpenAI (copié à partir de la page Vue d’ensemble). Ceci est nécessaire pour l'agent LangGraph.
`AZURE_OPENAI_DEPLOYMENT_NAME`	Nom du modèle de déploiement (copié depuis le volet Configuration des agents). Ceci 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 Configuration des agents). Cela est nécessaire pour appeler un agent Microsoft Foundry existant.

Note

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

Connectez-vous à 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.
Exécutez l’application localement :
```
npm run build
npm start
```
Lorsque vous voyez que votre application fonctionne sur le port 3000 et est disponible, sélectionnez Ouvrir dans le navigateur.
Sélectionnez le lien LangGraph Agent et le lien Agent Foundry pour tester l’interface de conversation. Si vous obtenez une réponse, votre application se connecte correctement à la ressource Microsoft Foundry.
De retour dans l’espace de code GitHub, déployez les modifications apportées à votre application.
```
azd up
```
Accédez à nouveau à l’application déployée et testez les agents de conversation.

LangGraph
Service de l’agent Foundry

Capture d’écran d’une session de chat avec un agent LangGraph.

Nettoyer les ressources

Lorsque vous avez terminé avec l’application, vous pouvez supprimer les ressources App Service pour éviter d’entraîner d’autres coûts :

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

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-11-30