Adicionar um aplicativo do App Service como uma ferramenta no Foundry Agent Service (Spring Boot)

Neste tutorial, você aprenderá a expor a funcionalidade de um aplicativo Web Spring Boot por meio do OpenAPI, adicioná-lo como uma ferramenta ao Serviço do Foundry Agent e interagir com seu aplicativo usando linguagem natural no playground de agentes.

Se seu aplicativo Web já tiver recursos úteis, como compras, reservas de hotéis ou gerenciamento de dados, é fácil disponibilizar esses recursos para um agente de IA no Serviço do Foundry Agent. Ao simplesmente adicionar um esquema OpenAPI ao seu aplicativo, você permite que o agente entenda e use os recursos do aplicativo quando ele responder aos prompts dos usuários. Isso significa que tudo o que seu aplicativo pode fazer, seu agente de IA também pode fazer, com esforço mínimo além de criar um endpoint OpenAPI para o seu aplicativo. Neste tutorial, você começa com um simples aplicativo de lista to-do. No final, você poderá criar, atualizar e gerenciar tarefas com um agente por meio da IA de conversa.

Pré-requisitos

Este tutorial pressupõe que você esteja trabalhando com o exemplo usado no Tutorial: Criar um aplicativo Web Java Spring Boot com o Serviço de Aplicativo do Azure no Linux e no Azure Cosmos DB.

No mínimo, abra o aplicativo de exemplo nos Codespaces do GitHub e implante o aplicativo executando azd up.

Adicionar a funcionalidade OpenAPI ao seu aplicativo Web

1. No codespace, abra pom.xml e adicione a seguinte dependência:

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.6.0</version>
   </dependency>
   

2. Abra src/main/java/com/microsoft/azure/appservice/examples/springbootmongodb/controller/TodoListController.java e adicione as seguintes importações.

   import io.swagger.v3.oas.annotations.Operation;
   import io.swagger.v3.oas.annotations.tags.Tag;
   

   A TodoListController classe implementa @RestController, portanto, você só precisa adicionar algumas anotações para torná-la compatível com o OpenAPI. Além disso, para tornar as APIs compatíveis com o Serviço do Agente do Foundry, você deve especificar a operationId propriedade na @Operation anotação (consulte Como usar o Serviço do Foundry Agent com Ferramentas Especificadas para OpenAPI: Pré-requisitos).

3. Localize a declaração de classe e adicione a @Tag anotação conforme mostrado no snippet a seguir:

   @RestController
   @Tag(name = "Todo List", description = "Todo List management APIs")
   public class TodoListController {
   

4. Localize a declaração do método getTodoItem e adicione a anotação @Operation com description e operationId, conforme mostrado no snippet a seguir:

   @Operation(description = "Returns a single todo item", operationId = "getTodoItem")
   @GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
   public TodoItem getTodoItem(@PathVariable("index") String index) {
   

5. Localize a declaração do método getAllTodoItems e adicione a anotação @Operation com description e operationId, conforme mostrado no snippet a seguir:

   @Operation(description = "Returns a list of all todo items", operationId = "getAllTodoItems")
   @GetMapping(path = "/api/todolist", produces = {MediaType.APPLICATION_JSON_VALUE})
   public List<TodoItem> getAllTodoItems() {
   

6. Localize a declaração do método addNewTodoItem e adicione a anotação @Operation com description e operationId, conforme mostrado no snippet a seguir:

   @Operation(description = "Creates a new todo item", operationId = "addNewTodoItem")
   @PostMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
   public String addNewTodoItem(@RequestBody TodoItem item) {
   

7. Localize a declaração do método updateTodoItem e adicione a anotação @Operation com description e operationId, conforme mostrado no snippet a seguir:

   @Operation(description = "Updates an existing todo item", operationId = "updateTodoItem")
   @PutMapping(path = "/api/todolist", consumes = MediaType.APPLICATION_JSON_VALUE)
   public String updateTodoItem(@RequestBody TodoItem item) {
   

8. Localize a declaração do método deleteTodoItem e adicione a anotação @Operation com description e operationId, conforme mostrado no snippet a seguir:

   @Operation(description = "Deletes a todo item by ID", operationId = "deleteTodoItem")
   @DeleteMapping("/api/todolist/{id}")
   public String deleteTodoItem(@PathVariable("id") String id) {
   

   Essa configuração mínima fornece as seguintes configurações, conforme documentado em springdoc-openapi:

   • Interface do usuário do Swagger em /swagger-ui.html.
   • Especificação OpenAPI em /v3/api-docs.

9. No terminal do codespace, execute o aplicativo com mvn spring-boot:run.

10. Selecione Abrir no Navegador.

11. Navegue até a interface do usuário do Swagger adicionando /swagger-ui.html à URL.

12. Confirme se as operações de API funcionam testando-as na interface do usuário do Swagger.

13. De volta ao terminal do codespace, implante suas alterações confirmando suas alterações (método GitHub Actions) ou execute azd up (método da CLI do Desenvolvedor do Azure).

14. Depois que suas alterações forem implantadas, navegue até https://<your-app's-url>/v3/api-docs e copie o esquema para mais tarde.

Criar um agente no Microsoft Foundry

1. No portal Foundry, no menu no canto superior direito, selecione New Foundry.

2. Se esta for a primeira vez no novo portal do Foundry, selecione o nome do projeto e selecione Criar novo projeto.

3. Dê um nome ao projeto e selecione Criar.

4. Selecione Começar a construir, em seguida Criar agente.

5. Dê um nome ao seu agente e selecione Criar. Quando o agente estiver pronto, você deverá ver a área de testes do agente.

   Observe os modelos que você pode usar e as regiões disponíveis.

6. No ambiente de trabalho do agente, expanda Ferramentas selecione Adicionar>Personalizada>Ferramenta OpenAPI>Criar.

7. Dê à ferramenta um nome e uma descrição. Na caixa de esquema OpenAPI 3.0+ , cole o esquema que você copiou anteriormente.

8. Selecione Criar ferramenta.

9. Clique em Salvar.

Testar o agente

1. Em Instruções, forneça algumas instruções simples, como "Use a ferramenta todosApp para ajudar a gerenciar tarefas".

2. Converse com o agente com as seguintes sugestões de prompt:

   • Mostre-me todas as tarefas.
   • Crie uma tarefa chamada "Crie três piadas de alface".
   • Mude isso para "Sugira três piadas de o que é o que é"

   

Melhores práticas de segurança

Ao expor APIs por meio do OpenAPI no Serviço de Aplicativo do Azure, siga estas práticas recomendadas de segurança:

• Autenticação e autorização: Proteja seus endpoints OpenAPI com a autenticação do Microsoft Entra. Para instruções passo a passo, consulte Pontos de extremidade OpenAPI Seguros para o Serviço de Agente da Fábrica. Você também pode proteger seus pontos de extremidade por meio do Gerenciamento de API do Azure com o Microsoft Entra ID e garantir que somente usuários ou agentes autorizados possam acessar as ferramentas.
• Validar e limpar dados de entrada: O código de exemplo neste tutorial omite a validação e a sanitização de entrada para simplicidade e clareza. Em cenários de produção, sempre implemente a validação e a sanitização adequadas para proteger seu aplicativo. Para o Spring, consulte Spring: Validando a entrada do formulário.
• Use HTTPS: O exemplo depende do Serviço de Aplicativo do Azure, que impõe HTTPS por padrão e fornece certificados TLS/SSL gratuitos para criptografar dados em trânsito.
• Limitar CORS: Restrinja o CORS (compartilhamento de recursos entre origens) somente a domínios confiáveis. Para obter mais informações, consulte Habilitar CORS.
• Aplicar limitação de taxa: use o Gerenciamento de API ou middleware personalizado para evitar ataques de abuso e negação de serviço.
• Ocultar endpoints confidenciais: Evite expor APIs internas ou administrativas em seu esquema OpenAPI.
• Examine o esquema OpenAPI: Verifique se o esquema OpenAPI não vaza informações confidenciais (como URLs internas, segredos ou detalhes de implementação).
• Mantenha as dependências atualizadas: Atualize regularmente os pacotes Do NuGet e monitore os avisos de segurança.
• Monitorar e registrar atividades: Ative o registro e monitore o acesso para detectar atividade suspeita.
• Use identidades gerenciadas: Ao chamar outros serviços do Azure, use identidades gerenciadas em vez de credenciais codificadas.

Para obter mais informações, consulte Proteger seu aplicativo do Serviço de Aplicativo e as práticas recomendadas para segurança da API REST.

Próxima etapa

Agora você habilitou seu aplicativo do Serviço de Aplicativo para ser usado como uma ferramenta pelo Serviço de Agente da Fábrica e para interagir com as APIs do seu aplicativo através de linguagem natural no ambiente de teste dos agentes. A partir daqui, você pode continuar a adicionar recursos ao seu agente no portal do Foundry, integrá-lo aos seus próprios aplicativos usando o SDK do Microsoft Foundry ou a API REST ou implantá-lo como parte de uma solução maior. Os agentes criados no Microsoft Foundry podem ser executados na nuvem, integrados a chatbots ou inseridos em aplicativos Web e móveis.

Mais recursos

• Integrar a IA aos aplicativos do Serviço de Aplicativo do Azure
• O que é o Serviço de Agente da Fábrica?