Compartilhar via

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)

Este tutorial demonstra como adicionar capacidade agente a um aplicativo Spring Boot WebFlux CRUD baseado em dados existente. Ele faz isso usando o Microsoft Semântico Kernel e o Foundry Agent Service.

Se seu aplicativo Web já tiver recursos úteis, como compras, reservas de hotéis ou gerenciamento de dados, é relativamente simples adicionar funcionalidade de agente ao seu aplicativo Web encapsulando essas funcionalidades em um plug-in (para LangGraph) ou como um ponto de extremidade OpenAPI (para o Serviço do Foundry Agent). Neste tutorial, você começa com um simples aplicativo de lista to-do. Ao final, você poderá criar, atualizar e gerenciar tarefas com um agente em um aplicativo do Serviço de Aplicativo.

O Kernel Semântico e o Serviço do Foundry Agent permitem criar aplicativos Web agente com funcionalidades controladas por IA. A tabela a seguir mostra algumas das considerações e compensações:

Consideração Núcleo Semântico Serviço de Agente da Fábrica
Performance Rápido (executado localmente) Mais lento (serviço gerenciado e remoto)
Desenvolvimento Código completo, controle máximo Código baixo, integração rápida
Testing Testes manuais/de unidade no código Playground integrado para testes rápidos
Escalabilidade App-managed Gerenciado pelo Azure, escalado automaticamente
Barreiras de segurança Implementação personalizada necessária Segurança de conteúdo integrada e moderação
Identidade Implementação personalizada necessária ID do agente embutido e autenticação
Enterprise Integração personalizada necessária Implantação embutida do Microsoft 365/Teams e chamadas de ferramentas integradas do Microsoft 365.

Neste tutorial, você aprenderá como:

  • Converta a funcionalidade de aplicativo existente em um plug-in para Kernel Semântico.
  • Adicione o plug-in a um agente kernel semântico e use-o em um aplicativo Web.
  • Converta a funcionalidade de aplicativo existente em um endpoint OpenAPI para o Foundry Agent Service.
  • Chame um agente do Foundry em um aplicativo Web.
  • Atribua as permissões necessárias para conectividade de identidade gerenciada.

Prerequisites

Abra o exemplo com codespaces

A maneira mais fácil de começar é usando o GitHub Codespaces, que fornece um ambiente de desenvolvimento completo com todas as ferramentas necessárias pré-instaladas.

Abrir em codespaces do GitHub.

  1. Navegue até o repositório GitHub em https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-java.

  2. Selecione o botão Código , selecione a guia Codespaces e selecione Criar codespace no principal.

  3. Aguarde alguns instantes para que o codespace seja inicializado. Quando estiver pronto, você verá um ambiente de desenvolvimento totalmente configurado no navegador.

  4. Execute o aplicativo localmente:

    mvn spring-boot:run

  5. Quando você vir que seu aplicativo em execução na porta 8080 está disponível, selecione Abrir no Navegador e adicione algumas tarefas.

Examinar o código do agente

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

Implantar o aplicativo de exemplo

O repositório de exemplo contém um modelo da CLI do Desenvolvedor do Azure (AZD), que cria um aplicativo do Serviço de Aplicativo com identidade gerenciada e implanta seu aplicativo de exemplo.

  1. No terminal, faça logon no Azure usando a CLI do Desenvolvedor do Azure:

    azd auth login

    Siga as instruções para concluir o processo de autenticação.

  2. Implante o aplicativo do Serviço de Aplicativo do Azure com o modelo do AZD:

    azd up

  3. Quando solicitado, dê as seguintes respostas:

    Question Answer
    Insira um novo nome de ambiente: Digite um nome exclusivo.
    Selecione uma Assinatura do Azure para usar: Selecione a assinatura.
    Escolha um grupo de recursos a ser usado: Selecione Criar um grupo de recursos.
    Selecione um local para criar o grupo de recursos em: Selecione Suécia Central.
    Insira um nome para o novo grupo de recursos: Digite ENTER.

  4. Na saída do AZD, localize a URL do seu aplicativo e navegue até ela no navegador. O URL fica assim na saída do AZD:

     Deploying services (azd deploy)

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

  5. Abra o esquema OpenAPI gerado automaticamente no https://....azurewebsites.net/api/schema caminho. Você precisará desse esquema mais tarde.

    Agora você tem um aplicativo do Serviço de Aplicativo com uma identidade gerenciada atribuída pelo sistema.

Criar e configurar o recurso microsoft foundry

  1. No portal do Foundry, verifique se o botão de opção Novo Foundry no topo está definido como ativo e 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. A maneira mais fácil de obter o endpoint do Azure OpenAI ainda é através do portal clássico. Selecione o botão de opção Novo Foundry e, em seguida, OpenAI do Azure; depois, copie a URL no ponto de extremidade do OpenAI do Azure para uso posterior.

    Captura de tela mostrando como copiar o ponto de extremidade OpenAI e o ponto de extremidade do projeto foundry no portal dofoundry.

Atribuir permissões necessárias

  1. No menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o recurso do projeto Foundry, e o que está na coluna Recurso pai é o recurso Foundry.

    Captura de tela mostrando como acessar rapidamente o recurso do Foundry ou o recurso de projeto do Foundry.

  2. Selecione o recurso Foundry no recurso Pai e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

  3. Adicione a seguinte função para a identidade gerenciada do aplicativo do Serviço de Aplicativos:

    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.

Configurar variáveis de conexão em seu aplicativo de exemplo

  1. Abra src/main/resources/application.properties. Usando os valores copiados anteriormente do portal do Foundry, configure as seguintes variáveis:

    Variable Description
    azure.openai.endpoint Endpoint do Azure OpenAI (copiado do portal clássico do Foundry).
    azure.openai.deployment Nome do modelo na implantação (copiado do ambiente de testes de modelos no novo portal Foundry).

    Note

    Para manter o tutorial simples, você usará essas variáveis em .env em vez de substituí-las com configurações de aplicativo no Serviço de Aplicativo.

    Note

    Para manter o tutorial simples, você usará essas variáveis em src/main/resources/application.properties em vez de substituí-las com configurações de aplicativo no Serviço de Aplicativo.

  2. Entre no Azure com a CLI do Azure:

    az login

    Isso permite que a biblioteca de clientes da Identidade do Azure no código de exemplo receba um token de autenticação para o usuário conectado. Lembre-se de que você adicionou a função necessária para esse usuário anteriormente.

  3. Execute o aplicativo localmente:

    mvn spring-boot:run

  4. Quando você vir que seu aplicativo em execução na porta 8080 está disponível, selecione Abrir no Navegador.

  5. Experimente a interface de chat. Se você receber uma resposta, seu aplicativo estará se conectando com êxito ao recurso Microsoft Foundry.

  6. De volta ao codespace do GitHub, implante as alterações do aplicativo.

    azd up

  7. Navegue até o aplicativo implantado novamente e teste os agentes de chat.

Limpar os recursos

Quando terminar de usar o aplicativo, você poderá excluir os recursos do Serviço de Aplicativo para evitar incorrer em custos adicionais:

azd down --purge

Como o modelo do AZD não inclui os recursos do Microsoft Foundry, você precisa excluí-los manualmente, se desejar.

Mais recursos

  • Last updated on