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

Capture d’écran d’une session de conversation achevée avec un agent Microsoft 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);
        }
    }

Lors du traitement des messages utilisateur, l’agent est appelé à l’aide invoke() de la configuration de message et de session de l’utilisateur pour assurer la continuité des conversations :

const result = await this.agent.invoke(
    { 
        messages: [
            { role: 'user', content: message }
        ]
    },
    { 
        configurable: { 
            thread_id: currentSessionId 
        } 
    }
);

Le FoundryTaskAgent utilise un modèle d’initialisation différée dans src/agents/FoundryTaskAgent.ts. Le code d’initialisation effectue les opérations suivantes :

• Crée un AIProjectClient à l’aide des informations d’identification Azure.
• Obtient un client OpenAI à partir du client de projet.
• Récupère l’agent par nom.
• Crée une nouvelle conversation pour la session.

// Create the AI Project client
this.project = new AIProjectClient(endpoint, new DefaultAzureCredential());
this.openAIClient = await this.project.getOpenAIClient();
this.agentName = agentName;

// Create a conversation for this session
const conversation = await this.openAIClient.conversations.create({
    items: [],
});
this.conversationId = conversation.id;

console.log(`Foundry agent initialized with name: ${this.agentName}, Conversation: ${this.conversationId}`);

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 :

/**
 * @swagger
 * /api/tasks:
 *   get:
 *     summary: Get all tasks
 *     operationId: getAllTasks
 *     responses:
 *       200:
 *         description: List of tasks
 */
router.get('/tasks', async (req: Request, res: Response) => {
    try {
        const tasks = await taskService.getAllTasks();
        res.json(tasks);
    } catch (error) {
        console.error('Error getting tasks:', error);
        res.status(500).json({ error: 'Failed to get tasks' });
    }
});

Lors du traitement des messages utilisateur, l’agent est appelé en ajoutant le message de l’utilisateur à la conversation et en appelant responses.create() avec la référence de l’agent :

// Add the user message to the conversation
await this.openAIClient.conversations.items.create(this.conversationId, {
    items: [{ type: 'message', role: 'user', content: message }],
});

// Generate response using the agent
const response = await this.openAIClient.responses.create(
    {
        conversation: this.conversationId,
    },
    {
        body: { agent: { name: this.agentName, type: 'agent_reference' } },
    }
);

1. Dans le portail Foundry, vérifiez que le bouton radio New Foundry en haut est activé et créez un projet.

2. Déployez un modèle de votre choix (consultez Démarrage rapide Microsoft Foundry : Créer des ressources).

3. Depuis le haut du model playground, copiez le nom du modèle.

4. Le moyen le plus simple d’obtenir le point de terminaison Azure OpenAI est toujours à partir du portail Classic. Sélectionnez le bouton radio New Foundry, puis Azure OpenAI, et copiez l’URL dans le point de terminaison Azure OpenAI pour une utilisation ultérieure.

   

1. Dans le portail Foundry, vérifiez que le bouton radio New Foundry en haut est défini sur actif, puis créez un projet.

2. Dans la page d’accueil, copiez le point d'accès du projet pour plus tard.

3. Sélectionnez Commencer à construire>Créer agent et suivez l’invite.

4. Dans le nouveau terrain de jeu de l’agent, créez un outil personnalisé OpenAPI pour appeler votre application web en sélectionnant Outils>Ajouter un>outil> OpenAPIpersonnalisé>Créer. 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, voir Se connecter à la spécification OpenAPI.

5. Veillez à sélectionner Enregistrer.

6. Sélectionnez Essayer dans le terrain de jeu et tester votre agent Foundry avec des invites telles que « Afficher toutes les tâches » et « Veuillez ajouter une tâche ».

   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.

1. Dans le menu supérieur du nouveau portail Foundry, sélectionnez Utiliser, puis sélectionnez Administrateur. Dans la ligne de votre projet Foundry, vous devez voir deux liens. La colonne Name est la ressource de projet Foundry, et celle de la colonne de ressource Parent est la ressource Foundry.

   

2. Sélectionnez la ressource Foundry dans la ressource parente , puis sélectionnez Gérer cette ressource dans le portail Azure. À partir du portail Azure, vous pouvez attribuer un accès en fonction du rôle pour la ressource à l’application web déployée.

3. Ajoutez le rôle suivant pour l’identité managée de l’application App Service :

   Ressource cible	Rôle requis	Nécessaire pour
   Fonderie	Utilisateur OpenAI de Cognitive Services	Service d’achèvement de conversation dans Microsoft Agent Framework.

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

1. Dans le menu supérieur du nouveau portail Foundry, sélectionnez Utiliser, puis sélectionnez Administrateur. Dans la ligne de votre projet Foundry, vous devez voir deux liens. La colonne Name est la ressource de projet Foundry, et celle de la colonne de ressource Parent est la ressource Foundry.

   

2. Sélectionnez la ressource de projet Foundry dans la colonne Nom , puis sélectionnez Gérer cette ressource dans le portail Azure. À partir du portail Azure, vous pouvez attribuer un accès en fonction du rôle pour la ressource à l’application web déployée.

3. Ajoutez le rôle suivant pour l’identité managée de l’application App Service :

   Ressource cible	Rôle requis	Nécessaire pour
   Projet de fonderie	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.

Capture d’écran d’une session de conversation achevée avec un agent Microsoft Foundry.