Samouczek: budowa aplikacji internetowej z funkcjami agencyjnymi w usłudze Azure App Service przy użyciu Microsoft Semantic Kernel lub Foundry Agent Service (Spring Boot)

Agent Semantic Kernel jest inicjowany w src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, gdy użytkownik wprowadzi pierwszy monit w nowej sesji przeglądarki.

Kod inicjowania można znaleźć w konstruktorze SemanticKernelAgentService (w pliku src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). Kod inicjowania wykonuje następujące czynności:

• Tworzy jądro z funkcją dokończenia rozmowy.
• Dodaje wtyczkę do jądra, która zamyka funkcjonalność aplikacji CRUD (w pliku src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). Interesujące części wtyczki to DefineKernelFunction adnotacje na deklaracjach metod oraz parametry description i returnType, które pomagają kernelowi mądrze wywołać wtyczkę.
• Tworzy agenta uzupełniania czatu i konfiguruje go tak, aby umożliwić modelowi sztucznej inteligencji automatyczne wywoływanie funkcji (FunctionChoiceBehavior.auto(true)).
• Tworzy wątek agenta, który automatycznie zarządza historią czatu.

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

Za każdym razem, gdy otrzymany zostanie monit, kod serwera używa ChatCompletionAgent.invokeAsync() do wywołania agenta, wykorzystując monit użytkownika i wątek agenta. Wątek agenta monitoruje historię czatu.

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

Agent Foundry jest inicjalizowany w pliku src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, gdy użytkownik wprowadzi pierwszy monit w nowej sesji przeglądarki.

Kod inicjowania można znaleźć w konstruktorze FoundryAgentService (w pliku src/main/java/com/example/crudtaskswithagent/service/FoundryAgentService.java). Kod inicjowania wykonuje następujące czynności:

• Tworzy obiekt AgentsClientBuilder z punktem końcowym i poświadczeniami.
• Kompiluje wyspecjalizowanych klientów asynchronicznych: ConversationsAsyncClient i ResponsesAsyncClient.
• Odwołuje się do agenta według nazwy (skonfigurowanej w portalu Foundry).
• Tworzy rozmowę dla sesji.

// Configure Foundry client with endpoint and credentials
AgentsClientBuilder builder = new AgentsClientBuilder()
        .endpoint(endpoint)
        .serviceVersion(AgentsServiceVersion.V2025_11_15_PREVIEW)
        .credential(new DefaultAzureCredentialBuilder().build());

// Build specialized async clients for conversations and responses
this.conversationsClient = builder.buildConversationsAsyncClient();
this.responsesClient = builder.buildResponsesAsyncClient();

// Reference the agent by name (configured in Foundry portal)
this.agentReference = new AgentReference(agentName);

// Create a conversation for this session
this.conversationId = conversationsClient.getConversationServiceAsync()
        .create()
        .get() // Blocking call - must be on boundedElastic thread
        .id();

Ten kod inicjowania nie definiuje żadnych funkcji agenta, ponieważ zwykle kompilujesz agenta w portalu Foundry. W ramach przykładowego scenariusza jest on również zgodny ze wzorcem OpenAPI pokazanym w Dodawanie aplikacji App Service jako narzędzia w usłudze Foundry Agent Service (Spring Boot) i udostępnia funkcjonalność CRUD jako punkt końcowy OpenAPI. Dzięki temu można dodać go do agenta później jako narzędzie do wywołania.

Adnotacje OpenAPI są definiowane w klasie TaskController. Na przykład trasa "GET /api/tasks" definiuje użycie operationId za pomocą adnotacji @Operation, zgodnie z wymaganiami narzędzia specyfikacji OpenAPI w usłudze Microsoft Foundry, oraz summary i description pomagają agentowi określić sposób wywoływania interfejsu API.

@GetMapping
@Operation(
    summary = "Get all tasks",
    description = "Retrieves all tasks from the database",
    operationId = "getAllTasks"
)
@ApiResponse(responseCode = "200", description = "List of tasks")
public Flux<TaskItem> getAllTasks() {
    return taskRepository.findAllOrderById();
}

Za każdym razem, gdy zostanie wyświetlony monit, kod serwera używa responsesClient.createWithAgentConversation() polecenia do wysyłania komunikatu do agenta usługi Foundry i pobierania odpowiedzi. Identyfikator konwersacji śledzi historię czatu.

// Send message to agent and get response
return responsesClient
    .createWithAgentConversation(agentReference, conversationId, paramsBuilder)
    .map(response -> {
        // Extract text from response - find the message item in output array
        return response.output().stream()
            .filter(item -> item.message().isPresent())
            .findFirst()
            .flatMap(item -> item.message())
            .map(msg -> !msg.content().isEmpty() && msg.content().get(0).isOutputText()
                ? msg.content().get(0).asOutputText().text()
                : "I received your message but couldn't generate a response.")
            .orElse("I received your message but couldn't generate a response.");
    })
    .timeout(Duration.ofSeconds(60))
    .onErrorResume(throwable -> {
        logger.error("Error processing message: {}", throwable.getMessage(), throwable);
        return Mono.just("Sorry, I encountered an error processing your request: " + throwable.getMessage());
    });

1. W portalu Foundry upewnij się, że górny przycisk radiowy New Foundry jest ustawiony na aktywny i utwórz projekt.

2. Wdróż wybrany model (zobacz Przewodnik Szybki start firmy Microsoft Foundry: tworzenie zasobów).

3. W górnej części placu zabaw modelu skopiuj nazwę modelu.

4. Najłatwiejszym sposobem na uzyskanie punktu końcowego Azure OpenAI jest wciąż skorzystanie z klasycznego portalu. Wybierz przycisk radiowy New Foundry, następnie pozycję Azure OpenAI, a potem skopiuj adres URL z punktu końcowego usługi Azure OpenAI na później.

   

1. W portalu Foundry upewnij się, że górny przycisk radiowy New Foundry jest ustawiony na aktywny i utwórz projekt.

2. Na stronie głównej skopiuj punkt końcowy projektu do późniejszego użycia.

3. Wybierz pozycję Rozpocznij tworzenie>agenta i postępuj zgodnie z monitem.

4. Na placu zabaw nowego agenta utwórz narzędzie OpenAPI do wywołania aplikacji internetowej, wybierając Narzędzia>Dodaj>własne>narzędzie OpenAPI>Utwórz. W okienku Konfiguracja dodaj akcję za pomocą narzędzia specyfikacji interfejsu OpenAPI. Użyj schematu OpenAPI pobranego z wdrożonej aplikacji internetowej i uwierzytelniania anonimowego . Aby uzyskać szczegółowe instrukcje, zobacz How to use the OpenAPI spec tool (Jak używać narzędzia specyfikacji Interfejsu OpenAPI).

   Kod aplikacji jest już skonfigurowany do uwzględnienia serwerów url i operationId, które są wymagane przez agenta. Aby uzyskać więcej informacji, zobacz Connect to OpenAPI Specification.

5. Pamiętaj, aby wybrać pozycję Zapisz.

6. Wybierz Wypróbuj w środowisku testowym i przetestuj agenta Foundry z poleceniami, takimi jak "Pokaż mi wszystkie zadania" i "Dodaj zadanie".

   Jeśli otrzymasz prawidłową odpowiedź, agent wykonuje wywołania narzędzi do punktu końcowego interfejsu OpenAPI w wdrożonej aplikacji internetowej.

1. W górnym menu nowego portalu Foundry wybierz pozycję Obsługa, a następnie wybierz pozycję Administrator. W wierszu projektu Foundry powinny zostać wyświetlone dwa linki. Element w kolumnie Name to zasób projektu Foundry, natomiast ten w kolumnie Zasób nadrzędny to zasób Foundry.

   

2. Wybierz zasób Foundry w zasobie nadrzędnym , a następnie wybierz pozycję Zarządzaj tym zasobem w witrynie Azure Portal. W witrynie Azure Portal możesz przypisać dostęp oparty na rolach dla zasobu do wdrożonej aplikacji internetowej.

3. Dodaj następującą rolę dla zarządzanej tożsamości aplikacji App Service.

   Zasób docelowy	Wymagana rola	Wymagane do
   Odlewnia	Użytkownik Usług Cognitive Services OpenAI	Usługa uzupełniania czatu w programie Microsoft Agent Framework.

   Aby uzyskać instrukcje, zobacz temat Przypisywanie ról platformy Azure za pomocą witryny Azure Portal.

1. W górnym menu nowego portalu Foundry wybierz pozycję Obsługa, a następnie wybierz pozycję Administrator. W wierszu projektu Foundry powinny zostać wyświetlone dwa linki. Element w kolumnie Name to zasób projektu Foundry, a ten w kolumnie Zasób nadrzędny to zasób Foundry.

   

2. Wybierz zasób projektu Foundry w kolumnie Nazwa , a następnie wybierz pozycję Zarządzaj tym zasobem w witrynie Azure Portal. W witrynie Azure Portal możesz przypisać dostęp oparty na rolach dla zasobu do wdrożonej aplikacji internetowej.

3. Dodaj następującą rolę dla zarządzanej tożsamości aplikacji App Service:

   Zasób docelowy	Wymagana rola	Wymagane do
   Projekt odlewniczy	Użytkownik sztucznej inteligencji platformy Azure	Odczytywanie i wywoływanie agenta usługi Foundry.

   Aby uzyskać instrukcje, zobacz temat Przypisywanie ról platformy Azure za pomocą witryny Azure Portal.