Adicionar uma aplicação de Serviço de Aplicações como ferramenta no Foundry Agent Service (Spring Boot)

Neste tutorial, vais aprender a expor a funcionalidade de uma aplicação web Spring Boot através do OpenAPI, adicioná-la como ferramenta ao Foundry Agent Service e interagir com a tua aplicação usando linguagem natural no playground dos agentes.

Se a sua aplicação web já tem funcionalidades úteis, como compras, reservas de hotel ou gestão de dados, é fácil disponibilizar essas capacidades a um agente de IA no Foundry Agent Service. Ao simplesmente adicionar um esquema OpenAPI ao seu aplicativo, você permite que o agente compreenda e use os recursos do seu aplicativo quando ele responde aos prompts dos usuários. Isso significa que tudo o que a sua aplicação pode fazer, o seu agente de IA também pode fazer, com o mínimo de esforço além de criar um endpoint OpenAPI para a sua aplicação. Neste tutorial, começas com uma aplicação de lista simples to-do. No final, você poderá criar, atualizar e gerenciar tarefas com um agente por meio de IA conversacional.

Pré-requisitos

Este tutorial pressupõe que você esteja trabalhando com o exemplo usado em 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 no GitHub Codespaces e implante o aplicativo executando azd up.

Adicionar funcionalidade OpenAPI ao seu aplicativo Web

1. No espaço de código, 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, então você só precisa adicionar algumas anotações para torná-lo compatível com OpenAPI. Além disso, para tornar as APIs compatíveis com o Foundry Agent Service, deve especificar a operationId propriedade na @Operation anotação ( ver Como usar o Foundry Agent Service com Ferramentas Especificadas OpenAPI: Pré-requisitos).

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

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

4. Encontre a declaração do método getTodoItem e adicione à anotação @Operation com description e operationId, conforme mostrado no trecho 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. Encontre a declaração do método getAllTodoItems e adicione à anotação @Operation com description e operationId, conforme mostrado no trecho 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. Encontre a declaração do método addNewTodoItem e adicione à anotação @Operation com description e operationId, conforme mostrado no trecho 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. Encontre a declaração do método updateTodoItem e adicione à anotação @Operation com description e operationId, conforme mostrado no trecho 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. Encontre a declaração do método deleteTodoItem e adicione à anotação @Operation com description e operationId, conforme mostrado no trecho 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:

   • Swagger UI na /swagger-ui.html.
   • Especificação OpenAPI em /v3/api-docs.

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

10. Selecione Abrirno navegador.

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

12. Confirme se as operações da 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 executando azd up (método Azure Developer CLI).

14. Depois que as 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 da Foundry, no menu superior direito, selecione Nova Foundry.

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

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

4. Seleciona Iniciar construção, depois Criar agente.

5. Dê um nome ao seu agente e selecione Criar. Quando o agente estiver pronto, deve visitar o parque infantil do agente.

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

6. No ambiente de testes do agente, expanda Ferramentas e selecione Adicionar>OpenAPI personalizada>Ferramenta>Criar.

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

8. Selecione Criar ferramenta.

9. Selecione Guardar.

Testar o agente

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

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

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

   

Práticas recomendadas de segurança

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

• Autenticação e autorização: proteja os seus pontos de extremidade OpenAPI com a autenticação do Microsoft Entra. Para obter instruções passo a passo, consulte Endpoints OpenAPI Seguros para o Foundry Agent Service. Você também pode proteger seus pontos de extremidade por trás do Gerenciamento de API do Azure com a ID do Microsoft Entra e garantir que apenas usuários ou agentes autorizados possam acessar as ferramentas.
• Valide e limpe os dados de entrada: O código de exemplo neste tutorial omite a validação e a limpeza de entrada para simplicidade e clareza. Em cenários de produção, sempre implemente a validação e a higienização adequadas para proteger seu aplicativo. Para Spring, consulte Spring: Validating Form Input.
• 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.
• Limite de CORS: Restrinja o CORS (Cross-Origin Resource Sharing) apenas a domínios confiáveis. Para obter mais informações, consulte Habilitar CORS.
• Aplicar limite de taxa: Use o Gerenciamento de API ou middleware personalizado para evitar abusos e ataques de negação de serviço.
• Ocultar pontos de extremidade sensíveis: Evite expor APIs internas ou administrativas em seu esquema OpenAPI.
• Revise o esquema OpenAPI: Certifique-se de que seu esquema OpenAPI não vaze informações confidenciais (como URLs internos, segredos ou detalhes de implementação).
• Mantenha as dependências atualizadas: Atualize regularmente os pacotes NuGet e monitore os avisos de segurança.
• Monitore e registre a atividade: Habilite o registro em log e monitore o acesso para detetar atividades suspeitas.
• 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 Práticas recomendadas para segurança da API REST.

Próximo passo

Agora ativou a sua aplicação de Serviço de Aplicações para ser usada como ferramenta pelo “Foundry Agent Service” e para interagir com as APIs da sua aplicação através de linguagem natural no ambiente de teste dos agentes. A partir daqui, pode continuar a adicionar funcionalidades ao seu agente no portal Foundry, integrá-lo nas suas próprias aplicações usando o Microsoft Foundry SDK ou a API REST, ou implementá-lo como parte de uma solução maior. Os agentes criados no Microsoft Foundry podem ser executados na cloud, integrados em chatbots ou integrados em aplicações web e móveis.

Mais recursos

• Integre a IA em seus aplicativos do Serviço de Aplicativo do Azure
• O que é o Foundry Agent Service?