Lernprogramm: Erstellen einer agentischen Web-App in Azure App Service mit LangGraph oder Foundry Agent Service (Node.js)

Die LangGraphTaskAgent Initialisierung erfolgt im Konstruktor in "src/agents/LangGraphTaskAgent.ts". Der Initialisierungscode führt folgendes aus:

• Konfiguriert den AzureChatOpenAI-Client mithilfe von Umgebungsvariablen.
• Erstellt den vordefinierten ReAct-Agent mit einer Reihe von CRUD-Tools für die Aufgabenverwaltung (siehe LangGraph: Verwenden des vordefinierten ReAct-Agents).
• Richtet die Speicherverwaltung ein (siehe LangGraph: Hinzufügen von Arbeitsspeicher zum vordefinierten ReAct-Agent).

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

Beim Verarbeiten von Benutzernachrichten wird der Agent mit invoke() der Nachrichten- und Sitzungskonfiguration des Benutzers für die Unterhaltungskontinuität aufgerufen:

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

Das FoundryTaskAgent verwendet ein faules Initialisierungsmuster in src/agents/FoundryTaskAgent.ts. Der Initialisierungscode führt folgendes aus:

• Erstellt ein AIProjectClient mit Azure-Anmeldeinformationen.
• Ruft einen OpenAI-Client vom Projektclient ab.
• Ruft den Agenten nach Namen ab.
• Erzeugt eine neue Kommunikation für die Sitzung.

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

Dieser Initialisierungscode definiert keine Funktionen für den Agent, da Sie normalerweise den Agent im Foundry-Portal erstellen würden. Im Rahmen des Beispielszenarios folgt es auch dem OpenAPI-Muster, das in add an App Service app as a tool in Foundry Agent Service (Node.js) dargestellt wird und seine CRUD-Funktionalität als OpenAPI-Endpunkt verfügbar macht. Auf diese Weise können Sie ihn später als aufrufbares Tool dem Agent hinzufügen.

Der OpenAPI-Code wird in "src/routes/api.ts" definiert. Beispielsweise definiert die Route "GET /api/tasks" in den JSDoc-Swagger-Kommentaren operationId , wie vom OpenAPI-Spezifikationstool in Microsoft Foundry erforderlich, und description hilft dem Agent zu bestimmen, wie die API aufgerufen werden soll:

/**
 * @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' });
    }
});

Beim Verarbeiten von Benutzernachrichten wird der Agent aufgerufen, indem die Nachricht des Benutzers zur Unterhaltung hinzugefügt und mit der Agentenreferenz responses.create() aufgerufen wird.

// 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. Vergewissern Sie sich im Foundry-Portal, dass die obere Neue Foundry-Schaltfläche auf aktiv festgelegt ist und erstellen Sie ein Projekt.

2. Stellen Sie ein Modell Ihrer Wahl bereit (siehe Schnellstart von Microsoft Foundry: Erstellen von Ressourcen).

3. Kopieren Sie den Namen des Modells aus dem oberen Bereich des Modell-Playrounds.

4. Die einfachste Möglichkeit zum Abrufen des Azure OpenAI-Endpunkts ist noch aus dem klassischen Portal. Wählen Sie die Schaltfläche Neues Foundry, dann Azure OpenAI und kopieren Sie die URL in Azure OpenAI Endpunkt für später.

   

1. Vergewissern Sie sich im Foundry-Portal, dass die obere Neue Foundry-Schaltfläche auf aktiv festgelegt ist und erstellen Sie ein Projekt.

2. Kopieren Sie auf der Startseite den Project-Endpunkt für einen späteren Zeitpunkt.

3. Wählen Sie "Beginnen Sie mit dem Erstellen>von Agenten" aus, und folgen Sie der Eingabeaufforderung.

4. Erstellen Sie im Playground des neuen Agents ein OpenAPI-Tool, um Ihre Web-App aufzurufen, indem Sie tools>Add>Custom>OpenAPI tool>Create auswählen. Fügen Sie im Setupbereich eine Aktion mit dem OpenAPI-Spezifikationstool hinzu. Verwenden Sie das OpenAPI-Schema, das Sie aus der bereitgestellten Web-App und der anonymen Authentifizierung erhalten. Ausführliche Schritte finden Sie unter Verwenden des OpenAPI-Spezifikationstools.

   Ihr Anwendungscode ist bereits so konfiguriert, dass er die url und operationId des Servers einbindet, die vom Agent benötigt werden. Weitere Informationen finden Sie unter Connect to OpenAPI Specification.

5. Wählen Sie " Speichern" aus.

6. Wählen Sie "In Playground testen" aus, und testen Sie Ihren Foundry-Agent mit Eingabeaufforderungen wie "Alle Aufgaben anzeigen" und "Bitte fügen Sie eine Aufgabe hinzu".

   Wenn Sie eine gültige Antwort erhalten, sendet der Agent Toolaufrufe an den OpenAPI-Endpunkt in Ihrer bereitgestellten Web-App.

1. Wählen Sie im oberen Menü des neuen Gießereiportals "Betreiben" und dann "Administrator" aus. In der Zeile für Ihr Foundry-Projekt sollten zwei Links angezeigt werden. Die Ressource in der Spalte Name ist die Projektressource von Foundry, und die Ressource in der Spalte Übergeordnete Ressource ist die Foundry-Ressource.

   

2. Wählen Sie die Foundry-Ressource in der übergeordneten Ressource aus, und wählen Sie dann im Azure-Portal "Diese Ressource verwalten" aus. Im Azure-Portal können Sie der bereitgestellten Web-App rollenbasierten Zugriff für die Ressource zuweisen.

3. Fügen Sie die folgende Rolle für die verwaltete Identität der App Service-Anwendung hinzu:

   Zielressource	Erforderliche Rolle	Erforderlich für
   Gießerei	Kognitive Dienste OpenAI-Nutzer	Der Chatabschlussdienst in Microsoft Agent Framework.

   Anweisungen hierzu finden Sie unter Zuweisen von Azure-Rollen über das Azure-Portal.

1. Wählen Sie im oberen Menü des neuen Gießereiportals "Betreiben" und dann "Administrator" aus. In der Zeile für Ihr Foundry-Projekt sollten zwei Links angezeigt werden. Die Ressource in der Spalte Name ist die Projektressource von Foundry, und die Ressource in der Spalte Übergeordnete Ressource ist die Foundry-Ressource.

   

2. Wählen Sie die Ressource "Foundry"-Projekt in der Spalte "Name " und dann im Azure-Portal "Diese Ressource verwalten" aus. Im Azure-Portal können Sie der bereitgestellten Web-App rollenbasierten Zugriff für die Ressource zuweisen.

3. Fügen Sie die folgende Rolle für die verwaltete Identität der App Service-Anwendung hinzu:

   Zielressource	Erforderliche Rolle	Erforderlich für
   Gießerei-Projekt	Azure AI-Benutzer	Lesen und Aufrufen des Foundry-Agents.

   Anweisungen hierzu finden Sie unter Zuweisen von Azure-Rollen über das Azure-Portal.