Freigeben über

Lernprogramm: Erstellen einer agentischen Web-App in Azure App Service mit Microsoft Semantic Kernel oder Foundry Agent Service (Spring Boot)

In diesem Lernprogramm wird veranschaulicht, wie Sie einer vorhandenen datengesteuerten Spring Boot WebFlux CRUD-Anwendung agentische Funktionen hinzufügen. Dazu wird der Microsoft Semantic Kernel and Foundry Agent Service verwendet.

Wenn Ihre Webanwendung bereits nützliche Funktionen wie Shopping, Hotelbuchung oder Datenverwaltung aufweist, ist es relativ einfach, Ihrer Webanwendung Agent-Funktionen hinzuzufügen, indem diese Funktionen in ein Plug-In (für LangGraph) oder als OpenAPI-Endpunkt (für Foundry Agent Service) eingeschlossen werden. In dieser Anleitung beginnen Sie mit einer einfachen To-Do-Listen-App. Am Ende können Sie Aufgaben mit einem Agent in einer App Service-App erstellen, aktualisieren und verwalten.

Sowohl der Semantic Kernel als auch der Foundry-Agent-Service ermöglichen Ihnen, agentenbasierte Webanwendungen mit KI-gesteuerten Funktionen zu erstellen. In der folgenden Tabelle sind einige der Überlegungen und Kompromisse aufgeführt:

Überlegung Semantischer Kernel Gießerei-Agentendienst
Leistung Schnell (wird lokal ausgeführt) Langsamer (verwalteter, Ferndienst)
Entwicklung Vollständiger Code, maximale Steuerung Geringer Code, schnelle Integration
Testen Manuelle Tests/Einheitstests im Code Integrierter Playground für schnelle Tests
Skalierbarkeit App-verwaltet Von Azure verwaltet, automatisch skaliert
Sicherheitsschutzschienen Benutzerdefinierte Implementierung erforderlich Integrierte Sicherheit und Moderation von Inhalten
Identität Benutzerdefinierte Implementierung erforderlich Integrierte Agent-ID und Authentifizierung
Enterprise Benutzerdefinierte Integration erforderlich Integrierte Microsoft 365/Teams-Bereitstellung und Integrierte Microsoft 365-Toolaufrufe.

In diesem Tutorial lernen Sie Folgendes:

  • Konvertieren Sie vorhandene App-Funktionen in ein Plug-In für semantischen Kernel.
  • Fügen Sie das Plug-In einem semantischen Kernel-Agent hinzu, und verwenden Sie es in einer Web-App.
  • Konvertieren Sie vorhandene App-Funktionen in einen OpenAPI-Endpunkt für den Foundry Agent Service.
  • Rufen Sie einen Foundry-Agent in einer Web-App auf.
  • Weisen Sie die erforderlichen Berechtigungen für verwaltete Identitätskonnektivität zu.

Prerequisites

Öffnen des Beispiels mit Codespaces

Die einfachste Möglichkeit für die ersten Schritte ist die Verwendung von GitHub Codespaces, die eine vollständige Entwicklungsumgebung mit allen erforderlichen Tools vorinstalliert bietet.

In GitHub Codespaces öffnen.

  1. Navigieren Sie zum GitHub-Repository unter https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-java.

  2. Wählen Sie die Schaltfläche "Code ", dann die Registerkarte " Codespaces " und dann " Codespace erstellen" im Hauptfeld aus.

  3. Warten Sie einige Augenblicke, bis Der Codespace initialisiert wird. Wenn Sie bereit sind, wird eine vollständig konfigurierte Entwicklungsumgebung in Ihrem Browser angezeigt.

  4. Führen Sie die Anwendung lokal aus:

    mvn spring-boot:run

  5. Wenn Sie sehen, dass Ihre Anwendung auf Port 8080 ausgeführt wird, wählen Sie "Im Browser öffnen" aus, und fügen Sie einige Aufgaben hinzu.

Überprüfen des Agentcodes

Der semantische Kernel-Agent wird in src/main/java/com/example/crudtaskswithagent/controller/AgentController.java initialisiert, wenn der Benutzer die erste Eingabeaufforderung in einer neuen Browsersitzung eingibt.

Sie finden den Initialisierungscode im SemanticKernelAgentService Konstruktor (in src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). Der Initialisierungscode führt folgendes aus:

  • Erstellt einen Kernel mit Abschluss des Chats.
  • Fügt ein Kernel-Plug-In hinzu, das die Funktionalität der CRUD-Anwendung kapselt (in src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). Die interessanten Teile des Plug-Ins sind die DefineKernelFunction Anmerkungen zu den Methodendeklarationen und die Parameter descriptionreturnType, die dem Kernel ermöglichen, das Plug-In intelligent aufzurufen.
  • Erstellt einen Chat-Vervollständigungs-Agent und konfiguriert ihn so, dass das KI-Modell funktionen automatisch aufruft (FunctionChoiceBehavior.auto(true)).
  • Erstellt einen Agentthread, der den Chatverlauf automatisch verwaltet.
        // Create OpenAI client
        OpenAIAsyncClient openAIClient = new OpenAIClientBuilder()
                .endpoint(endpoint)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildAsyncClient();
        
        // Create chat completion service
        OpenAIChatCompletion chatCompletion = OpenAIChatCompletion.builder()
                .withOpenAIAsyncClient(openAIClient)
                .withModelId(deployment)
                .build();
        
        // Create kernel plugin from the task plugin
        KernelPlugin kernelPlugin = KernelPluginFactory.createFromObject(taskCrudPlugin, "TaskPlugin");
        
        // Create kernel with TaskCrudPlugin and chat completion service
        Kernel kernel = Kernel.builder()
                .withAIService(OpenAIChatCompletion.class, chatCompletion)
                .withPlugin(kernelPlugin)
                .build();
        
        // Use automatic function calling
        InvocationContext invocationContext = InvocationContext.builder()
            .withFunctionChoiceBehavior(FunctionChoiceBehavior.auto(true))
            .build();

        // Create ChatCompletionAgent
        configuredAgent = ChatCompletionAgent.builder()
                .withKernel(kernel)
                .withName("TaskAgent")
                .withInvocationContext(invocationContext)
                .withInstructions(
                    "You are an agent that manages tasks using CRUD operations. " +
                    "Use the TaskCrudPlugin functions to create, read, update, and delete tasks. " +
                    "Always call the appropriate plugin function for any task management request. " +
                    "Don't try to handle any requests that are not related to task management."
                )
                .build();
        
    } catch (Exception e) {
        logger.error("Error initializing SemanticKernelAgentService: {}", e.getMessage(), e);
    }
}

this.agent = configuredAgent;

// Initialize thread for this instance
this.thread = ChatHistoryAgentThread.builder().build();

Bei jedem Empfang des Prompts verwendet der Servercode ChatCompletionAgent.invokeAsync(), um den Agent mit der Benutzeraufforderung und dem Agentthread aufzurufen. Der Agentthread verfolgt den Chatverlauf.

// Use the agent to process the message with automatic function calling
return agent.invokeAsync(userMessageContent, thread)
        .<String>map(responses -> {
            
            if (responses != null && !responses.isEmpty()) {
                // Process all responses and concatenate them
                StringBuilder combinedResult = new StringBuilder();
                
                for (int i = 0; i < responses.size(); i++) {
                    var response = responses.get(i);
                    
                    // Update thread with the last response thread (as per Microsoft docs)
                    if (i == responses.size() - 1) {
                        var responseThread = response.getThread();
                        if (responseThread instanceof ChatHistoryAgentThread) {
                            this.thread = (ChatHistoryAgentThread) responseThread;
                        }
                    }
                    
                    // Get response content
                    ChatMessageContent<?> content = response.getMessage();
                    String responseContent = content != null ? content.getContent() : "";
                    
                    if (!responseContent.isEmpty()) {
                        if (combinedResult.length() > 0) {
                            combinedResult.append("\n\n"); // Separate multiple responses
                        }
                        combinedResult.append(responseContent);
                    }
                }
                
                String result = combinedResult.toString();
                if (result.isEmpty()) {
                    result = "No content returned from agent.";
                }
                return result;
            } else {
                return "I'm sorry, I couldn't process your request. Please try again.";
            }
        })
        .onErrorResume(throwable -> {
            logger.error("Error in processMessage: {}", throwable.getMessage(), throwable);
            return Mono.just("Error processing message: " + throwable.getMessage());
        });

Bereitstellen der Beispielanwendung

Das Beispiel-Repository enthält eine Azure Developer CLI (AZD)-Vorlage, die eine App Service-App mit verwalteter Identität erstellt und Ihre Beispielanwendung bereitstellt.

  1. Melden Sie sich im Terminal mit Azure Developer CLI bei Azure an:

    azd auth login

    Folgen Sie den Anweisungen, um den Authentifizierungsprozess abzuschließen.

  2. Stellen Sie die Azure App Service-App mit der AZD-Vorlage bereit:

    azd up

  3. Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Antworten:

    Question Answer
    Geben Sie einen neuen Umgebungsnamen ein: Geben Sie einen eindeutigen Namen ein.
    Wählen Sie ein Azure-Abonnement aus, das Sie verwenden möchten: Wählen Sie das Abonnement aus.
    Wählen Sie eine zu verwendende Ressourcengruppe aus: Wählen Sie Eine neue Ressourcengruppe erstellen aus.
    Wählen Sie einen Speicherort aus, in dem die Ressourcengruppe erstellt werden soll: Wählen Sie "Schweden Zentral" aus.
    Geben Sie einen Namen für die neue Ressourcengruppe ein: Geben Sie Eingeben ein.

  4. Suchen Sie in der AZD-Ausgabe die URL für Ihre App, und navigieren Sie im Browser dorthin. Die URL sieht in der AZD-Ausgabe wie folgt aus:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

  5. Öffnen Sie das automatisch generierte OpenAPI-Schema im https://....azurewebsites.net/api/schema Pfad. Sie benötigen dieses Schema später.

    Sie verfügen jetzt über eine App Service-App mit einer vom System zugewiesenen verwalteten Identität.

Erstellen und Konfigurieren der Microsoft Foundry-Ressource

  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.

    Screenshot, der zeigt, wie der OpenAI-Endpunkt und der Gießereiprojektendpunkt im Gießereiportal kopiert werden.

Zuweisen erforderlicher Berechtigungen

  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.

    Screenshot, der zeigt, wie Sie schnell zur Gießereiressource oder Gießereiprojektressource wechseln.

  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.

Konfigurieren von Verbindungsvariablen in Ihrer Beispielanwendung

  1. Öffnen Sie src/main/resources/application.properties. Konfigurieren Sie mithilfe der Werte, die Sie zuvor aus dem Foundry-Portal kopiert haben, die folgenden Variablen:

    Variable Description
    azure.openai.endpoint Azure OpenAI-Endpunkt (kopiert aus dem klassischen Foundry-Portal).
    azure.openai.deployment Modellname in der Bereitstellung (kopiert aus dem Modell-Playground im New Foundry Portal).

    Note

    Um das Lernprogramm einfach zu halten, verwenden Sie diese Variablen in env , anstatt sie mit App-Einstellungen in App Service zu überschreiben.

    Note

    Um das Lernprogramm einfach zu halten, verwenden Sie diese Variablen in src/main/resources/application.properties , anstatt sie mit App-Einstellungen in App Service zu überschreiben.

  2. Melden Sie sich mit der Azure CLI bei Azure an:

    az login

    Dadurch kann die Azure Identity-Clientbibliothek im Beispielcode ein Authentifizierungstoken für den angemeldeten Benutzer empfangen. Denken Sie daran, dass Sie die erforderliche Rolle für diesen Benutzer zuvor hinzugefügt haben.

  3. Führen Sie die Anwendung lokal aus:

    mvn spring-boot:run

  4. Wenn Sie sehen, dass Ihre Anwendung auf Port 8080 ausgeführt wird, wählen Sie "Im Browser öffnen" aus.

  5. Probieren Sie die Chatschnittstelle aus. Wenn Sie eine Antwort erhalten, stellt Ihre Anwendung eine erfolgreiche Verbindung mit der Microsoft Foundry-Ressource her.

  6. Stellen Sie ihre App-Änderungen wieder im GitHub-Codespace bereit.

    azd up

  7. Navigieren Sie erneut zur bereitgestellten Anwendung, und testen Sie die Chat-Agents.

Bereinigen von Ressourcen

Wenn Sie mit der Anwendung fertig sind, können Sie die App Service-Ressourcen löschen, um weitere Kosten zu vermeiden:

azd down --purge

Da die AZD-Vorlage die Microsoft Foundry-Ressourcen nicht enthält, müssen Sie sie bei Bedarf manuell löschen.

Weitere Ressourcen

  • Last updated on