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);
        }
    }

L’échantillon déployé est protégé par l’authentification App Service et utilise un seul thread LangGraph sélectionné par le serveur. Lorsque vous traitez les messages utilisateur, l’agent invoque invoke() avec le message de l’utilisateur et l’identifiant du thread géré par le serveur :

private readonly conversationThreadId = 'authenticated-conversation';

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

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 conversation gérée par le serveur pour l’expérience d’exemple authentifiée par App Service.

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

// App Service authentication protects this app, so this sample intentionally
// keeps one server-managed authenticated conversation for the Foundry path.
const conversation = await this.openAIClient.conversations.create({
    items: [],
});
this.conversationId = conversation.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 (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 :

try {
    // 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, 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. Sur la page d’accueil, copiez le point de terminaison Azure OpenAI pour plus tard.

1. Dans le portail Foundry, créez un projet.

2. Sur la page d’accueil, copiez le point de terminaison du projet pour l’utiliser plus tard.

3. Sélectionnez Commencer la construction et suivez l’invitation.

4. Sélectionnez Outils>Ajouter>Ajouter des outils>Personnalisé>Outil OpenAPI>Créer. Dans le volet Installation , ajoutez une action avec l’outil de spécification OpenAPI.

5. Collez le schéma OpenAPI que vous avez copié depuis l’application App Service authentifiée.

6. Pour la méthode d’authentification, sélectionnez Identité managée.

7. Pour Audience, collez la valeur Audience d’identité managée Foundry OpenAPI figurant dans la sortie d’AZD. Elle ressemble à :

   api://<generated-client-id>
   

8. Enregistrez l’outil et l’agent.

Permettre à la ressource Foundry parent d’appeler l’API de tâche

1. Dans le portail Foundry, sélectionnez Gérer dans le menu supérieur.

2. Dans les détails du Project, sélectionnez la ressource parente de votre project, puis sélectionnez Ouvrir dans le portail Azure.

3. Copiez l’ID d’objet (principal) de l’identité attribuée par le système. Trouvez cette identité dans Microsoft Entra ID, et copiez son ID d’application. Pour des étapes détaillées, voir Identifier la ressource Foundry parent.

4. Dans le terminal Codespace, stockez l’ID de l’application dans l’environnement AZD et mettez à jour la configuration d’authentification du Service App :

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. Dans le portail Foundry, sélectionnez Gérer dans le menu supérieur.

2. Dans les détails du Project, sélectionnez la ressource parente de votre project, puis sélectionnez Ouvrir dans le portail Azure.

   Depuis le portail Azure, vous pouvez attribuer un accès basé sur les rôles pour la ressource.

3. Ajoutez le rôle suivant à l’identité gérée de l’application App Service ainsi qu’à l’utilisateur que vous utilisez avec az login :

   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 portail Foundry, sélectionnez Gérer dans le menu supérieur.

2. Dans les détails du Project, sélectionnez Ouvrir dans le portail Azure.

   Depuis le portail Azure, vous pouvez attribuer un accès basé sur les rôles pour le projet.

3. Ajoutez le rôle suivant à l’identité gérée de l’application App Service ainsi qu’à l’utilisateur que vous utilisez avec az login :

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