Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Serviço de Agente da Fábrica (.NET)

Neste tutorial, você aprenderá a expor a funcionalidade de um aplicativo ASP.NET Core 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çará com um aplicativo simples de listas chamado 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: 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 nos Codespaces do GitHub e implante o aplicativo executando azd up.

Adicionar a funcionalidade OpenAPI ao seu aplicativo Web

1. No terminal do codespace, adicione os pacotes do 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 Controladores/TodosController.cs, adicione os seguintes métodos de API. Para torná-los compatíveis com o Foundry Agent Service, você deve especificar a OperationId propriedade no SwaggerOperation atributo (consulte Como usar o Foundry Agent Service com Ferramentas Especificadas para 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. Na parte superior de Controllers/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 do MVC e dos métodos de API.

4. Em Program.cs, registre o serviço do gerador do Swagger. Isso habilita a documentação do OpenAPI para sua API, que permite que o Serviço do Foundry Agent entenda suas APIs. Especifique a URL do servidor. O Serviço do Foundry Agent 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. Esse middleware atende à documentação do OpenAPI gerada em runtime, tornando-o acessível por meio de um navegador.

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

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

7. Selecione Abrir no Navegador.

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

9. Confirme se as operações de 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 execute azd up (método da CLI do Desenvolvedor do Azure).

11. Depois que suas 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 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 dados de entrada: o código de exemplo verifica ModelState.IsValid o método, que CreateTodo garante que os dados de entrada correspondam aos atributos de validação do modelo. Para obter mais informações, consulte a 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.
• 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.

Para seguir a próxima etapa e aprender a executar seu agente diretamente no Serviço de Aplicativo do Azure, confira o tutorial a seguir:

Mais recursos

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