Zelfstudie: Een agentische web-app bouwen in Azure App Service met Microsoft Semantic Kernel of Foundry Agent Service (Spring Boot)

Deze zelfstudie laat zien hoe u agentische mogelijkheden toevoegt aan een bestaande datagestuurde Spring Boot WebFlux CRUD-toepassing. Dit doet u met behulp van Microsoft Semantic Kernel en Foundry Agent Service.

Als uw webtoepassing al nuttige functies heeft, zoals winkelen, hotelreservering of gegevensbeheer, is het relatief eenvoudig om agentfunctionaliteit toe te voegen aan uw webtoepassing door deze functies in een invoegtoepassing (voor LangGraph) of als een OpenAPI-eindpunt (voor Foundry Agent Service) te verpakken. In deze handleiding begint u met een eenvoudige to-do lijstapp. Aan het einde kunt u taken maken, bijwerken en beheren met een agent in een App Service-app.

Met zowel Semantic Kernel als Foundry Agent Service kunt u agentische webtoepassingen bouwen met AI-gestuurde mogelijkheden. In de volgende tabel ziet u enkele overwegingen en afwegingen:

Overweging Semantische Kernel Foundry Agentendienst
Performance Snel (lokaal uitgevoerd) Trager (beheerde, externe service)
Ontwikkeling Volledige code, maximaal beheer Low-code, snelle integratie
Testing Handmatige/eenheidstests in code Ingebouwde speeltuin voor snel testen
Schaalbaarheid App-managed Door Azure beheerd, automatisch geschaald
Veiligheidsrails Aangepaste implementatie vereist Ingebouwde inhoudsveiligheid en toezicht
Identiteit Aangepaste implementatie vereist Ingebouwde agent-id en verificatie
Enterprise Aangepaste integratie vereist Ingebouwde microsoft 365/Teams-implementatie en geïntegreerde hulpprogramma-aanroepen van Microsoft 365.

In deze handleiding leer je hoe je:

  • Bestaande app-functionaliteit converteren naar een invoegtoepassing voor Semantic Kernel.
  • Voeg de invoegtoepassing toe aan een Semantic Kernel-agent en gebruik deze in een web-app.
  • Bestaande app-functionaliteit converteren naar een OpenAPI-eindpunt voor Foundry Agent Service.
  • Roep een Foundry-agent aan in een web-app.
  • Wijs de vereiste machtigingen toe voor connectiviteit met beheerde identiteiten.

Prerequisites

Het voorbeeld openen met Codespaces

De eenvoudigste manier om aan de slag te gaan is door GitHub Codespaces te gebruiken. Dit biedt een volledige ontwikkelomgeving met alle vereiste hulpprogramma's die vooraf zijn geïnstalleerd.

Openen in GitHub Codespaces.

  1. Navigeer naar de GitHub-opslagplaats op https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-java.

  2. Klik op de knop Code, selecteer het tabblad Codespaces en selecteer Codespace op main maken.

  3. Wacht even totdat uw Codespace is geïnitialiseerd. Wanneer u klaar bent, ziet u een volledig geconfigureerde ontwikkelomgeving in uw browser.

  4. Voer de toepassing lokaal uit:

    mvn spring-boot:run

  5. Wanneer u ziet dat uw toepassing actief is op poort 8080, selecteer Openen in Browser en voeg een paar taken toe.

De agentcode controleren

De Semantic Kernel-agent wordt geïnitialiseerd in src/main/java/com/example/crudtaskswithagent/controller/AgentController.java wanneer de gebruiker de eerste prompt invoert in een nieuwe browsersessie.

U vindt de initialisatiecode in de SemanticKernelAgentService constructor (in src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). De initialisatiecode doet het volgende:

  • Hiermee maakt u een kernel met chatvoltooiing.
  • Voegt een kernelinvoegtoepassing toe die de functionaliteit van de CRUD-toepassing inkapselt (in src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). De interessante onderdelen van de invoegtoepassing zijn de DefineKernelFunction annotaties in de methodeverklaringen en de description en returnType parameters die de kernel helpen de invoegtoepassing intelligent aan te roepen.
  • Hiermee maakt u een chatvoltooiingsagent en configureert u deze zodat het AI-model automatisch functies kan aanroepen (FunctionChoiceBehavior.auto(true)).
  • Hiermee maakt u een agentthread waarmee de chatgeschiedenis automatisch wordt beheerd.
        // 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();

Telkens wanneer de prompt wordt ontvangen, gebruikt de servercode ChatCompletionAgent.invokeAsync() om de agent aan te roepen met de gebruikersprompt en de agentthread. De agentthread houdt de chatgeschiedenis bij.

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

De voorbeeldtoepassing implementeren

De voorbeeldopslagplaats bevat een AZD-sjabloon (Azure Developer CLI), waarmee een App Service-app met beheerde identiteit wordt gemaakt en uw voorbeeldtoepassing wordt geïmplementeerd.

  1. Meld u in de terminal aan bij Azure met behulp van Azure Developer CLI:

    azd auth login

    Volg de instructies om het verificatieproces te voltooien.

  2. Implementeer de Azure App Service-app met de AZD-sjabloon:

    azd up

  3. Geef de volgende antwoorden wanneer u hierom wordt gevraagd:

    Question Answer
    Voer een nieuwe omgevingsnaam in: Voer een unieke naam in.
    Selecteer een Azure-abonnement dat u wilt gebruiken: Selecteer het abonnement.
    Kies een resourcegroep die u wilt gebruiken: Selecteer Een nieuwe resourcegroep maken.
    Selecteer een locatie waarin u de resourcegroep wilt maken in: Selecteer Zweden - centraal.
    Voer een naam in voor de nieuwe resourcegroep: Typ Enter.

  4. Zoek in de AZD-uitvoer de URL van uw app en navigeer ernaar in de browser. De URL ziet er in de AZD-uitvoer zo uit:

     Deploying services (azd deploy)

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

  5. Open het automatisch gegenereerde OpenAPI-schema op het https://....azurewebsites.net/api/schema pad. U heeft dit schema later nodig.

    U hebt nu een App Service-app met een door het systeem toegewezen beheerde identiteit.

De Microsoft Foundry-resource maken en configureren

  1. Maak in het Foundry-portaal een project.

  2. Een model van uw keuze implementeren (zie Snelstartgids voor Microsoft Foundry: Resources maken).

  3. Kopieer de naam van het model vanaf de bovenkant van de modelspeelplaats.

  4. Kopieer op de startpagina het Azure OpenAI-eindpunt voor later.

Vereiste machtigingen toewijzen

  1. Selecteer in het Foundry-portaal Beheren in het bovenste menu.

  2. Selecteer in Project details de Ouderresource van je project en selecteer vervolgens Open in Azure portal.

    Vanuit het Azure-portaal kun je rolgebaseerde toegang voor de resource toewijzen.

  3. Voeg de volgende rol toe voor zowel de beheerde identiteit van de App Service-app als de gebruiker waarmee je werkt az login:

    Doelresource Vereiste rol Vereist voor
    Gieterij Cognitive Services OpenAI-gebruiker De voltooiingsservice voor chats in Microsoft Agent Framework.

    Zie Azure-rollen toewijzen via Azure Portal voor instructies.

Verbindingsvariabelen configureren in uw voorbeeldtoepassing

  1. Open src/main/resources/application.properties. Configureer de volgende variabelen met behulp van de waarden die u eerder hebt gekopieerd uit de Foundry-portal:

    Variable Description
    azure.openai.endpoint Azure OpenAI endpoint (gekopieerd van de Foundry portal homepage).
    azure.openai.deployment Modelnaam in de implementatie (gekopieerd uit de modelspeeltuin in de nieuwe Foundry-portal).

    Note

    Als u de zelfstudie eenvoudig wilt houden, gebruikt u deze variabelen in .env in plaats van ze te overschrijven met app-instellingen in App Service.

    Note

    Als u de zelfstudie eenvoudig wilt houden, gebruikt u deze variabelen in src/main/resources/application.properties in plaats van ze te overschrijven met app-instellingen in App Service.

  2. Meld u aan bij Azure met de Azure CLI:

    az login

    Hierdoor kan de Azure Identity-clientbibliotheek in de voorbeeldcode een verificatietoken ontvangen voor de aangemelde gebruiker. Houd er rekening mee dat u de vereiste rol voor deze gebruiker eerder hebt toegevoegd.

  3. Voer de toepassing lokaal uit:

    mvn spring-boot:run

  4. Wanneer u ziet dat uw toepassing beschikbaar is op poort 8080, selecteert u Openen in de browser.

  5. Probeer de chatinterface uit. Als u een antwoord krijgt, maakt uw toepassing verbinding met de Microsoft Foundry-resource.

  6. Implementeer uw app-wijzigingen in de GitHub-codespace.

    azd up

  7. Ga opnieuw naar de geïmplementeerde toepassing en test de chatagents.

Veelgestelde vragen

Hoe voeg ik retrieval augmented generation (RAG) toe aan de Foundry-agent?

Deze richtlijn geldt voor het Foundry Agent Service-pad in deze tutorial. Het verandert niet de implementaties van LangGraph, Semantic Kernel of Microsoft Agent Framework die in het andere tabblad worden getoond.

Maak of selecteer een kennisbank van Foundry IQ, en verbind deze vervolgens met de Foundry Agent Service-agent. De verbinding wordt voor de agent beschikbaar gesteld als een beheerde MCP-kennistool.

De App Service-code blijft dezelfde agent bij naam aanroepen via zijn bestaande Foundry-client en agent_reference. De webapp heeft geen directe integratie met Azure AI Zoeken of een eigen MCP-client nodig. Als de gebruikersinterface bronnen toont, verwerk dan de citatie-annotaties die door de agent zijn teruggegeven.

De hulpbronnen opschonen

Wanneer u klaar bent met de toepassing, kunt u de App Service-resources verwijderen om verdere kosten te voorkomen:

azd down --purge

Aangezien de AZD-sjabloon de Microsoft Foundry-resources niet bevat, moet u ze desgewenst handmatig verwijderen.

Meer middelen

  • Last updated on