Tutorial: Criar um aplicativo web agente no Serviço de Aplicativo do Azure com o Kernel Semântico da Microsoft ou o Serviço de Agente da Fábrica (Spring Boot)

O agente kernel semântico é inicializado em src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, quando o usuário insere o primeiro prompt em uma nova sessão do navegador.

Você pode encontrar o código de inicialização no SemanticKernelAgentService construtor (em src/main/java/com/example/crudtaskswithagent/service/SemanticKernelAgentService.java). O código de inicialização faz o seguinte:

• Cria um kernel com a conclusão do chat.
• Adiciona um plug-in de kernel que encapsula a funcionalidade do aplicativo CRUD (em src/main/java/com/example/crudtaskswithagent/plug-in/TaskCrudPlugin.java). As partes interessantes do plug-in são as DefineKernelFunction anotações nas declarações de método e os parâmetros description e returnType que ajudam o kernel a chamar o plug-in de maneira inteligente.
• Cria um agente de conclusão de chat e o configura para permitir que o modelo de IA invoque automaticamente funções (FunctionChoiceBehavior.auto(true)).
• Cria um thread de agente que gerencia automaticamente o histórico de chat.

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

Sempre que o prompt é recebido, o código do servidor usa ChatCompletionAgent.invokeAsync() para invocar o agente com o prompt do usuário e o thread do agente. O thread do agente mantém o controle do histórico de chat.

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

O agente Foundry é inicializado em src/main/java/com/example/crudtaskswithagent/controller/AgentController.java, quando o usuário insere o primeiro prompt em uma nova sessão do navegador.

Você pode encontrar o código de inicialização no FoundryAgentService construtor (em src/main/java/com/example/crudtaskswithagent/service/FoundryAgentService.java). O código de inicialização faz o seguinte:

• Cria um AgentsClientBuilder com ponto de extremidade e credenciais.
• Cria clientes assíncronos especializados: ConversationsAsyncClient e ResponsesAsyncClient.
• Faz referência ao agente pelo nome (configurado no portal do Foundry).
• Cria uma conversa para a sessão.

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

Esse código de inicialização não define nenhuma funcionalidade para o agente, pois você normalmente compilaria o agente no portal do Foundry. Como parte do cenário de exemplo, também segue o padrão OpenAPI mostrado em Adicionar um aplicativo do Serviço de Aplicativos como ferramenta no Serviço do Agente do Foundry (Spring Boot) e disponibiliza sua funcionalidade CRUD como um endpoint OpenAPI. Isso permite adicioná-lo ao agente posteriormente como uma ferramenta invocável.

As anotações OpenAPI são definidas na TaskController classe. Por exemplo, a rota "GET /api/tasks" define operationId com a anotação @Operation, conforme exigido pela ferramenta de especificação OpenAPI no Microsoft Foundry e summary e description ajudam o agente a determinar como chamar a 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();
}

Sempre que o prompt é recebido, o código do servidor usa responsesClient.createWithAgentConversation() para enviar a mensagem para o agente Foundry e recuperar a resposta. A ID da conversa acompanha o histórico do chat.

// 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. No portal da Foundry, crie um projeto.

2. Implante um modelo de sua escolha (consulte o Início Rápido do Microsoft Foundry: Criar recursos).

3. Na parte superior da área de testes do modelo, copie o nome dele.

4. Na página inicial, copie o endpoint do Azure OpenAI para depois.

1. No portal da Foundry, crie um projeto.

2. Na página inicial, copie o endpoint do Project para uso posterior.

3. Selecione Começar a construir e siga o prompt.

4. No playground do novo agente, crie uma ferramenta OpenAPI para chamar seu aplicativo web selecionando Ferramentas>Adicionar>Adicionar ferramentas>Personalizado>Ferramenta OpenAPI>Criar. No painel Instalação , adicione uma ação com a ferramenta de especificação OpenAPI. Use o esquema OpenAPI que você obtém do aplicativo Web implantado e da autenticação anônima . Para obter etapas detalhadas, consulte Como usar a ferramenta de especificação OpenAPI.

   Seu código de aplicativo já está configurado para incluir o url e operationId do servidor, que são necessários para o agente. Para obter mais informações, consulte Connect to OpenAPI Specification.

5. Certifique-se de selecionar Salvar.

6. Selecione Experimentar no playground e teste seu agente do Foundry com prompts como "Mostrar-me todas as tarefas" e "Adicione uma tarefa".

   Se você receber uma resposta válida, o agente está fazendo chamadas de ferramenta para o ponto de extremidade OpenAPI no seu aplicativo Web implantado.

1. No portal Foundry, selecione Gerenciar no menu superior.

2. Em Detalhes do projeto, selecione o recurso pai do seu projeto e selecione Abrir no portal do Azure.

   Pelo portal Azure, você pode atribuir acesso baseado em função para o recurso.

3. Adicione a seguinte função tanto à identidade gerenciada do aplicativo do App Service quanto ao usuário que você usa com az login:

   Recurso de destino	Função necessária	Necessário para
   Fundição	Usuário dos Serviços Cognitivos OpenAI	O serviço de conclusão de chat no Microsoft Agent Framework.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.

1. No portal Foundry, selecione Gerenciar no menu superior.

2. Nos detalhes do Project, selecione Abrir no portal do Azure.

   Pelo portal do Azure, você pode atribuir acesso baseado em funções para o projeto.

3. Adicione a seguinte função tanto à identidade gerenciada do aplicativo do App Service quanto ao usuário que você usa com az login:

   Recurso de destino	Função necessária	Necessário para
   Projeto de fundimento	Usuário do Foundry	Lendo e chamando o agente do Foundry.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.