Oktatóanyag: Ügynökalapú webalkalmazás létrehozása az Azure App Service-ben a Microsoft Szemantic Kernel vagy a Foundry Agent Service használatával (Spring Boot)

Ez az oktatóanyag bemutatja, hogyan adhat ügynöki képességeket egy meglévő adatvezérelt Spring Boot WebFlux CRUD-alkalmazáshoz. Ezt a Microsoft Szemantic Kernel és a Foundry Agent Service használatával teszi.

Ha a webalkalmazás már rendelkezik olyan hasznos funkciókkal, mint a vásárlás, a szállodai foglalás vagy az adatkezelés, viszonylag egyszerű ügynökfunkciókat hozzáadni a webalkalmazáshoz úgy, hogy ezeket a funkciókat egy beépülő modulban (a LangGraphhoz) vagy OpenAPI-végpontként (a Foundry Agent Service-hez) csomagolja. Ebben az oktatóanyagban egy egyszerű to-do listaalkalmazással kezd. A végére létrehozhat, frissíthet és kezelhet feladatokat egy App Service-alkalmazásban lévő ügynökkel.

Mind a Szemantic Kernel, mind az Foundry Agent Service lehetővé teszi, hogy AI-vezérelt képességekkel rendelkező ügynökalapú webalkalmazásokat hozzon létre. Az alábbi táblázat néhány szempontot és kompromisszumot mutat be:

Megfontolás Szemantikus kernel Öntödei Ügynökségi Szolgáltatás
Performance Gyors (helyben fut) Lassabb (felügyelt, távoli szolgáltatás)
Fejlődés Teljes kód, maximális vezérlés Alacsony kód, gyors integráció
Testing Manuális/egységtesztek kódban Beépített játszótér a gyors teszteléshez
Skálázhatóság App-managed Azure által felügyelt, automatikusan skálázott
Biztonsági védőkorlátok Egyéni megvalósítás szükséges Beépített tartalombiztonság és moderálás
Személyazonosság Egyéni megvalósítás szükséges Beépített ügynökazonosító és -hitelesítés
Vállalati Egyéni integráció szükséges A Microsoft 365/Teams beépített üzembe helyezése és a Microsoft 365 integrált eszközhívásai.

Ebben az oktatóanyagban a következőket sajátíthatja el:

  • Meglévő alkalmazásfunkciók konvertálása a Szemantic Kernel beépülő moduljába.
  • Adja hozzá a beépülő modult egy Szemantikus Kernel-ügynökhöz, és használja egy webalkalmazásban.
  • Meglévő alkalmazásfunkciók átalakítása OpenAPI-végponttá a Foundry Agent Service-hez.
  • Hívjon meg egy Foundry ügynököt egy webalkalmazásban.
  • Rendelje hozzá a felügyelt identitáskapcsolathoz szükséges engedélyeket.

Prerequisites

A minta megnyitása a Codespaces használatával

Az első lépések legegyszerűbb módja a GitHub Codespaces használata, amely teljes fejlesztői környezetet biztosít az összes szükséges előre telepített eszközzel.

Megnyitás a GitHub Codespacesben.

  1. Lépjen a GitHub-adattárra a következő helyen https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-java: .

  2. Válassza a Kód gombot, válassza a Kódterek lapot, majd a Fő kódtér létrehozása lehetőséget.

  3. Várjon néhány percet a Codespace inicializálására. Ha elkészült, egy teljesen konfigurált fejlesztői környezetet fog látni a böngészőben.

  4. Futtassa az alkalmazást helyileg:

    mvn spring-boot:run

  5. Ha azt látja, hogy az alkalmazás a 8080-s porton fut, válassza a Megnyitás böngészőben lehetőséget, és adjon hozzá néhány feladatot.

Az ügynökkód áttekintése

A Szemantic Kernel-ügynök inicializálása az src/main/java/com/example/crudtaskswithagent/controller/AgentController.java nyelven történik, amikor a felhasználó egy új böngésző munkamenetben adja meg az első kérdést.

Az inicializálási kódot a SemanticKernelAgentService konstruktorban találja ( src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). Az inicializálási kód a következőket teszi:

  • Létrehoz egy kernelt a csevegés befejezésével.
  • Hozzáad egy kernel beépülő modult, amely magában foglalja a CRUD-alkalmazás funkcióit ( src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). A beépülő modul érdekes részei a DefineKernelFunction metódusdeklarációk széljegyzetei, valamint azok a description paraméterek, returnType amelyek segítenek a kernelnek intelligensen meghívni a beépülő modult.
  • Létrehoz egy csevegés-befejező ügynököt, és úgy konfigurálja, hogy az AI-modell automatikusan meghívja a függvényeket (FunctionChoiceBehavior.auto(true)).
  • Létrehoz egy ügynökszálat, amely automatikusan kezeli a csevegési előzményeket.
        // 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();

A rendszer minden alkalommal, amikor a kérés érkezik, a kiszolgálókód a felhasználói kéréssel és az ügynökszállal hívja ChatCompletionAgent.invokeAsync() meg az ügynököt. Az ügynökszál nyomon követi a csevegési előzményeket.

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

A mintaalkalmazás üzembe helyezése

A mintaadattár egy Azure Developer CLI-sablont (AZD) tartalmaz, amely létrehoz egy App Service-alkalmazást felügyelt identitással, és üzembe helyezi a mintaalkalmazást.

  1. A terminálon jelentkezzen be az Azure-ba az Azure Developer CLI használatával:

    azd auth login

    Kövesse az utasításokat a hitelesítési folyamat befejezéséhez.

  2. Az Azure App Service-alkalmazás üzembe helyezése az AZD-sablonnal:

    azd up

  3. Amikor megkérdezik, adja meg a következő válaszokat:

    Question Answer
    Adjon meg egy új környezetnevet: Írjon be egy egyedi nevet.
    Válassza ki a használni kívánt Azure-előfizetést: Válassza ki az előfizetést.
    Válasszon egy használandó erőforráscsoportot: Válassza az Új erőforráscsoport létrehozása lehetőséget.
    Válasszon ki egy helyet az erőforráscsoport létrehozásához a következő helyen: Válassza a Közép-Svédország lehetőséget.
    Adja meg az új erőforráscsoport nevét: Írja be az Enter billentyűt.

  4. Az AZD kimenetében keresse meg az alkalmazása URL-jét, és nyissa meg azt a böngészőben. Az URL-cím így néz ki az AZD-kimenetben:

     Deploying services (azd deploy)

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

  5. Nyissa meg az automatikusan létrehozott OpenAPI-sémát az https://....azurewebsites.net/api/schema elérési úton. Később szüksége lesz erre a sémára.

    Most már rendelkezik egy, a rendszer által hozzárendelt felügyelt identitással rendelkező App Service-alkalmazással.

A Microsoft Foundry-erőforrás létrehozása és konfigurálása

  1. Az Foundry portálon győződjön meg arról, hogy a felső Új Öntöde választógomb aktív, és hozzon létre egy projektet.

  2. Helyezzen üzembe egy tetszőleges modellt (lásd a Microsoft Foundry rövid útmutatóját: Erőforrások létrehozása).

  3. A modell játszóterének tetejéről másolja ki a modell nevét.

  4. Az Azure OpenAI-végpont lekérésének legegyszerűbb módja továbbra is a klasszikus portálon érhető el. Válassza a New Foundry rádiógombot, majd az Azure OpenAI-t, és másolja az URL-címet az Azure OpenAI végpont-ról későbbi használatra.

    Képernyőkép az OpenAI-végpont és az öntödei projektvégpont másolásáról az öntödei portálon.

A szükséges engedélyek hozzárendelése

  1. Az új Foundry portál felső menüjében válassza a Üzemeltetés, majd a Rendszergazda lehetőséget. Az Foundry-projekt sorában két hivatkozásnak kell megjelennie. A Név oszlopban a Foundry projekt erőforrása, a Szülő erőforrás oszlopban pedig a Foundry erőforrás található.

    Képernyőkép arról, hogyan léphet gyorsan az öntödei erőforrásra vagy az öntödei projekterőforrásra.

  2. Válassza ki a Foundry erőforrást a szülő erőforrásban, majd válassza az erőforrás kezelése opciót az Azure portálon. Az Azure Portalon szerepköralapú hozzáférést rendelhet az erőforráshoz az üzembe helyezett webalkalmazáshoz.

  3. Adja hozzá a következő szerepkört az App Service-alkalmazás felügyelt identitásához:

    Célerőforrás Kötelező szerepkör A következőhöz szükséges:
    Öntöde Cognitive Services OpenAI-felhasználó A Csevegés befejezése szolgáltatás a Microsoft Agent Frameworkben.

    Útmutatásért lásd: Azure-szerepkörök hozzárendelése az Azure-portál használatával.

Kapcsolatváltozók konfigurálása a mintaalkalmazásban

  1. Nyissa meg az src/main/resources/application.properties elemet. Az Foundry portálról korábban másolt értékek használatával konfigurálja a következő változókat:

    Variable Description
    azure.openai.endpoint Azure OpenAI-végpont (a klasszikus Foundry portálról másolva).
    azure.openai.deployment Modell neve az üzembe helyezésben (az új Foundry portál modelljátszótérről másolva).

    Note

    Az oktatóanyag egyszerűsége érdekében ezeket a változókat az .env alkalmazásban fogja használni ahelyett, hogy felülírja őket az App Service alkalmazásbeállításaival.

    Note

    Az oktatóanyag egyszerűsége érdekében ezeket a változókat az src/main/resources/application.properties függvényben fogja használni ahelyett, hogy felülírja őket az App Service alkalmazásbeállításaival.

  2. Jelentkezzen be az Azure-ba az Azure CLI-vel:

    az login

    Ez lehetővé teszi, hogy a mintakódban szereplő Azure Identity-ügyfélkódtár hitelesítési jogkivonatot kapjon a bejelentkezett felhasználó számára. Ne feledje, hogy korábban hozzáadta a felhasználóhoz szükséges szerepkört.

  3. Futtassa az alkalmazást helyileg:

    mvn spring-boot:run

  4. Ha azt látja, hogy az alkalmazás a 8080-s porton fut, válassza a Megnyitás böngészőben lehetőséget.

  5. Próbálja ki a csevegőfelületet. Ha választ kap, az alkalmazás sikeresen csatlakozik a Microsoft Foundry-erőforráshoz.

  6. A GitHub-kódtérben helyezze üzembe az alkalmazás módosításait.

    azd up

  7. Lépjen újra az üzembe helyezett alkalmazásra, és tesztelje a csevegőügynököket.

Erőforrások tisztítása

Ha végzett az alkalmazással, törölheti az App Service-erőforrásokat a további költségek elkerülése érdekében:

azd down --purge

Mivel az AZD-sablon nem tartalmazza a Microsoft Foundry-erőforrásokat, szükség esetén manuálisan kell törölnie őket.

További erőforrások

  • Last updated on