Руководство по созданию агентного веб-приложения в Службе приложений Azure с помощью семантического ядра Майкрософт или службы агента Foundry (Spring Boot)

Агент семантического ядра инициализирован в src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, когда пользователь вводит первый запрос в новом сеансе браузера.

Код инициализации можно найти в конструкторе SemanticKernelAgentService (в src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). Код инициализации выполняет следующие действия:

• Создает ядро с завершением чата.
• Добавляет плагин ядра, который инкапсулирует функциональность приложения CRUD (в src/main/java/com/example/crudtaskswithagent/plugin/TaskCrudPlugin.java). Интересные части подключаемого модуля — это аннотации в объявлениях метода и параметры DefineKernelFunction и description, которые помогают ядру умно вызывать подключаемый модуль.
• Создает агент завершения чата и настраивает его, чтобы модель ИИ автоматически вызывала функции (FunctionChoiceBehavior.auto(true)).
• Создает поток агента, который автоматически управляет историей чата.

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

Каждый раз при получении запроса код сервера используется ChatCompletionAgent.invokeAsync() для вызова агента с помощью запроса пользователя и потока агента. Поток агента отслеживает историю чата.

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

Агент Foundry инициализирован в src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, когда пользователь вводит первый запрос в новом сеансе браузера.

Код инициализации можно найти в конструкторе FoundryAgentService (в src/main/java/com/example/crudtaskswithagent/service/FoundryAgentService.java). Код инициализации выполняет следующие действия:

• Создает AgentsClientBuilder с конечной точкой и учетными данными.
• Создает специализированные асинхронные клиенты: ConversationsAsyncClient и ResponsesAsyncClient.
• Ссылается на агента по его имени, которое настроено в портале Foundry.
• Создает чат для сессии.

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

Этот код инициализации не определяет какие-либо функциональные возможности агента, так как обычно создается агент на портале Foundry. В рамках примера сценария он также следует шаблону OpenAPI, представленному в разделе «Добавить приложение службы App Service в качестве инструмента» в Foundry Agent Service (Spring Boot), и делает его функциональность CRUD доступной в качестве конечной точки OpenAPI. Это позволяет добавить его в агент позже в качестве вызываемой функции.

Аннотации OpenAPI определены в TaskController классе. Например, маршрут GET /api/tasks задается operationId с помощью @Operation аннотации, в соответствии с требованиями инструмента спецификации OpenAPI в Microsoft Foundry, а summarydescription также помогает агенту определить, как вызвать 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();
}

При каждом получении запроса код сервера используется responsesClient.createWithAgentConversation() для отправки сообщения агенту Foundry и получения ответа. Идентификатор беседы отслеживает журнал чата.

// 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. На портале Foundry убедитесь, что верхний переключатель New Foundry установлен как "Активный," и создайте проект.

2. Разверните модель выбранного варианта (см. краткое руководство по Microsoft Foundry: создание ресурсов).

3. В верхней части игровой площадки модели скопируйте имя модели.

4. Самый простой способ получить конечную точку Azure OpenAI по-прежнему с классического портала. Нажмите переключатель New Foundry, затем переключатель Azure OpenAI, и скопируйте URL-адрес в в конечной точке Azure OpenAI на потом.

   

1. На портале Foundry убедитесь, что верхний переключатель New Foundry установлен как "Активный," и создайте проект.

2. Скопируйте конечную точку проекта для использования позже.

3. Нажмите кнопку "Начать создание> и следуйте запросу.

4. В тестовой среде нового агента создайте инструмент OpenAPI для вызова вашего веб-приложения, выбрав Инструменты>Добавить>Пользовательский>инструмент OpenAPI>Создать. В области установки добавьте действие с помощью средства спецификации OpenAPI. Используйте схему OpenAPI, полученную из развернутого веб-приложения и анонимной проверки подлинности. Подробные инструкции см. в разделе "Использование средства спецификации OpenAPI".

   Ваш код приложения уже настроен, чтобы включать url и operationId сервера, которые необходимы агенту. Дополнительные сведения см. в разделе "Подключение к спецификации OpenAPI".

5. Не забудьте нажать кнопку "Сохранить".

6. Выберите "Попробовать на игровой площадке" и протестируйте агент Foundry с помощью запросов, таких как "Показать мне все задачи" и "Добавьте задачу".

   Если вы получаете допустимый ответ, агент совершает вызовы инструментов к конечной точке OpenAPI в вашем развернутом веб-приложении.

1. В верхнем меню нового портала Foundry выберите "Работа", а затем выберите "Администратор". В строке проекта Foundry вы увидите две ссылки. Тот, что в столбце Name, — это ресурс проекта Foundry, а тот, что в столбце Parent resource, — ресурс Foundry.

   

2. Выберите ресурс Foundry в родительском ресурсе и выберите "Управление этим ресурсом" на портале Azure. С портала Azure можно назначить роль-ориентированный доступ для управления развернутым веб-приложением и его ресурсами.

3. Добавьте следующую роль для управляемой идентификации приложения службы приложений:

   Целевой ресурс	Требуемая роль	Требуется для
   Литейный завод	Пользователь когнитивных сервисов OpenAI	Служба завершения чата в Microsoft Agent Framework.

   Инструкции см. в разделе Назначение ролей Azure с помощью портала Azure.

1. В верхнем меню нового портала Foundry выберите "Работа", а затем выберите "Администратор". В строке проекта Foundry вы увидите две ссылки. Тот, что в столбце Name, — это ресурс проекта Foundry, а тот, что в столбце Parent resource, — ресурс Foundry.

   

2. Выберите ресурс проекта Foundry в столбце "Имя" , а затем выберите "Управление этим ресурсом" на портале Azure. С портала Azure можно назначить роль-ориентированный доступ для управления развернутым веб-приложением и его ресурсами.

3. Добавьте следующую роль для управляемой идентификации приложения службы приложений:

   Целевой ресурс	Требуемая роль	Требуется для
   Проект Foundry	Пользователь Foundry	Чтение и вызов агента Foundry.

   Инструкции см. в разделе Назначение ролей Azure с помощью портала Azure.