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

Neste tutorial, vais aprender a expor a funcionalidade de uma aplicação ASP.NET Core 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: Implantar um aplicativo ASP.NET Core e do Banco de Dados SQL do Azure no Serviço de Aplicativo do Azure.

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 terminal codespace, adicione os pacotes NuGet Swashbuckle ao seu projeto:

   dotnet add package Swashbuckle.AspNetCore --version 6.5.0
   dotnet add package Swashbuckle.AspNetCore.Annotations --version 6.5.0
   

2. Em Controllers/TodosController.cs, adicione os seguintes métodos de API. Para os tornar compatíveis com o Foundry Agent Service, deve especificar a OperationId propriedade no SwaggerOperation atributo (veja Como usar o Foundry Agent Service com Ferramentas Especificadas OpenAPI: Pré-requisitos).

       // GET: api/todos
       [HttpGet("api/todos")]
       [SwaggerOperation(Summary = "Gets all Todo items", OperationId = "GetTodos")]
       [ProducesResponseType(typeof(IEnumerable<Todo>), 200)]
       public async Task<ActionResult<IEnumerable<Todo>>> GetTodos()
       {
           return await _context.Todo.ToListAsync();
       }
   
       // GET: api/todos/5
       [HttpGet("api/todos/{id}")]
       [SwaggerOperation(Summary = "Gets a Todo item by ID", OperationId = "GetTodoById")]
       [ProducesResponseType(typeof(Todo), 200)]
       [ProducesResponseType(404)]
       public async Task<ActionResult<Todo>> GetTodo(int id)
       {
           var todo = await _context.Todo.FindAsync(id);
   
           if (todo == null)
           {
               return NotFound();
           }
   
           return todo;
       }
   
   
   // POST: api/todos
   [HttpPost("api/todos")]
   [ProducesResponseType(StatusCodes.Status201Created)]
   [ProducesResponseType(StatusCodes.Status400BadRequest)]
   [SwaggerOperation(Summary = "Creates a new todo item.", Description = "Creates a new todo item and returns it.", OperationId = "CreateTodo")]
   public async Task<IActionResult> CreateTodo([FromBody] Todo todo)
   {
       if (!ModelState.IsValid)
       {
           return BadRequest(ModelState);
       }
       _context.Add(todo);
       await _context.SaveChangesAsync();
       return CreatedAtAction(nameof(GetTodo), new { id = todo.ID }, todo);
   }
   
   // PUT: api/todos/{id}
   [HttpPut("api/todos/{id}")]
   [ProducesResponseType(StatusCodes.Status204NoContent)]
   [ProducesResponseType(StatusCodes.Status400BadRequest)]
   [ProducesResponseType(StatusCodes.Status404NotFound)]
   [SwaggerOperation(Summary = "Updates a todo item.", Description = "Updates an existing todo item by ID.", OperationId = "UpdateTodo")]
   public async Task<IActionResult> UpdateTodo(int id, [FromBody] Todo todo)
   {
       // Use the id from the URL fragment only, ignore mismatching check
       if (!TodoExists(id))
       {
           return NotFound();
       }
       todo.ID = id;
       _context.Entry(todo).State = EntityState.Modified;
       await _context.SaveChangesAsync();
       return NoContent();
   }
   
   // DELETE: api/todos/{id}
   [HttpDelete("api/todos/{id}")]
   [ProducesResponseType(StatusCodes.Status204NoContent)]
   [ProducesResponseType(StatusCodes.Status404NotFound)]
   [SwaggerOperation(Summary = "Deletes a todo item.", Description = "Deletes a todo item by ID.", OperationId = "DeleteTodo")]
   public async Task<IActionResult> DeleteTodo(int id)
   {
       var todo = await _context.Todo.FindAsync(id);
       if (todo == null)
       {
           return NotFound();
       }
       _context.Todo.Remove(todo);
       await _context.SaveChangesAsync();
       return NoContent();
   }
   

3. No topo de Comandos/TodosController.cs, adicione o seguinte usando:

   using Swashbuckle.AspNetCore.Annotations;
   

   Esse código está duplicando a funcionalidade do controlador existente, o que é desnecessário, mas você o manterá para simplificar. Uma prática recomendada seria mover a lógica do aplicativo para uma classe de serviço e, em seguida, chamar os métodos de serviço das ações MVC e dos métodos da API.

4. Em Program.cs, registre o serviço gerador Swagger. Isto permite a documentação OpenAPI para a sua API, que permite ao Foundry Agent Service compreender as suas APIs. Certifique-se de especificar a URL do servidor. O Foundry Agent Service precisa de um esquema que contenha a URL do servidor.

   builder.Services.AddSwaggerGen(c =>
   {
       c.EnableAnnotations();
       var websiteHostname = Environment.GetEnvironmentVariable("WEBSITE_HOSTNAME");
       if (!string.IsNullOrEmpty(websiteHostname))
       {
           c.AddServer(new Microsoft.OpenApi.Models.OpenApiServer { Url = $"https://{websiteHostname}" });
       }
   });
   

5. Em Program.cs, habilite o middleware Swagger. Este middleware serve a documentação OpenAPI gerada em tempo de execução, tornando-a acessível através de um navegador.

   app.UseSwagger();
   app.UseSwaggerUI();
   

6. No terminal codespace, execute o aplicativo com dotnet run.

7. Selecione Abrirno navegador.

8. Navegue até a interface do usuário do Swagger adicionando /swagger/index.html à URL.

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

10. 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).

11. Depois que as alterações forem implantadas, navegue até https://<your-app's-url>/swagger/v1/swagger.json 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 Serviço de Agente Foundry. Você também pode proteger os seus pontos de extremidade atrás do Azure API Management com Microsoft Entra ID e garantir que apenas utilizadores ou agentes autorizados possam aceder às ferramentas.
• Valide os dados de entrada: O código de exemplo verifica o ModelState.IsValid no método CreateTodo, o que assegura que os dados de entrada correspondam aos atributos de validação do modelo. Para obter mais informações, consulte Validação de modelo no ASP.NET Core.
• 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.

Para dar o próximo passo e saber como executar seu agente diretamente no Serviço de Aplicativo do Azure, consulte o seguinte tutorial:

Mais recursos

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