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

Das bereitgestellte Sample ist durch App-Service-Authentifizierung geschützt und verwendet einen vom Server ausgewählten LangGraph-Thread. Wenn Sie Nachrichten von Benutzern verarbeiten, ruft der Agent invoke() mit der Nachricht des Benutzers und der vom Server verwalteten Thread-ID auf:

private readonly conversationThreadId = 'authenticated-conversation';

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

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 serverseitig verwaltete Konversation für das mit App Service authentifizierte Beispielszenario.

// 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;

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.

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. Im Foundry-Portal 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. Auf der Startseite kopieren Sie den Azure OpenAI-Endpunkt für später.

1. Im Foundry-Portal erstellen Sie ein Projekt.

2. Kopieren Sie auf der Startseite den Project-Endpunkt für die spätere Nutzung.

3. Wähle "Beginnen mit dem Bauen " und folge dem Prompt.

4. Wählen Sie Tools>Hinzufügen>Tools hinzufügen>Benutzerdefiniert>OpenAPI-Tool>Erstellen aus. Fügen Sie im Setupbereich eine Aktion mit dem OpenAPI-Spezifikationstool hinzu.

5. Füge das OpenAPI-Schema ein, das du aus der authentifizierten App Service-App kopiert hast.

6. Wählen Sie für die Authentifizierungsmethodeverwaltete Identität aus.

7. Für Audience fügen Sie den Wert für die verwaltete Identität von Foundry OpenAPI aus der AZD-Ausgabe ein. Es ähnelt:

   api://<generated-client-id>
   

8. Bewahren Sie das Tool und den Agenten auf.

Erlauben Sie der übergeordneten Foundry-Ressource, die Task-API aufzurufen.

1. Im Foundry-Portal wählen Sie im oberen Menü "Verwalten " aus.

2. In Project Details wählen Sie die Elternressource Ihres Projekts aus und wählen Sie dann im Azure-Portal öffnen.

3. Kopieren Sie die Objekt-(Haupt-)ID der systemzugewiesenen Identität. Finden Sie diese Identität in der Microsoft Entra ID und kopieren Sie deren Anwendungs-ID. Für detaillierte Schritte siehe Find the parent Foundry resource identity.

4. Im Codespace-Terminal speichern Sie die Anwendungs-ID in der AZD-Umgebung und aktualisieren Sie die App Service-Authentifizierungskonfiguration:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. Im Foundry-Portal wählen Sie im oberen Menü "Verwalten " aus.

2. In Project Details wählen Sie die Elternressource Ihres Projekts aus und wählen Sie dann im Azure-Portal öffnen.

   Vom Azure-Portal aus können Sie rollenbasierten Zugriff für die Ressource zuweisen.

3. Fügen Sie die folgende Rolle sowohl für die verwaltete Identität der App Service-App als auch für den Benutzer hinzu, den Sie mit az login verwenden:

   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. Im Foundry-Portal wählen Sie im oberen Menü "Verwalten " aus.

2. In Project Details wählen Sie im Azure Portal öffnen.

   Über das Azure-Portal können Sie rollenbasierten Zugriff für das Projekt zuweisen.

3. Fügen Sie die folgende Rolle sowohl für die verwaltete Identität der App Service-App als auch für den Benutzer hinzu, den Sie mit az login verwenden:

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

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