Adicionar um aplicativo do App Service como uma ferramenta no Foundry Agent Service (Node.js)

Neste tutorial, você aprenderá a expor a funcionalidade de um aplicativo Express.js 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.

Prerequisites

Este tutorial pressupõe que você esteja trabalhando com o exemplo usado no Tutorial: Implantar um aplicativo Web Node.js + MongoDB no 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 o pacote NPM do Swagger-jsdoc do NuGet ao seu projeto:

   npm install swagger-jsdoc
   

2. Abra routes/index.js. Na parte inferior do arquivo, acima de module.exports = router;, adicione as seguintes funções de API. Para torná-los compatíveis com o Serviço do Agente do Foundry, você deve especificar a operationId propriedade na anotação (consulte @swagger).

   router.get('/schema', function(req, res, next) {
     try {
       const swaggerJsdoc = require('swagger-jsdoc');
   
       res.json(
         swaggerJsdoc(
           {
             definition: {
               openapi: '3.0.0',
               servers: [
                 {
                   url: `${req.protocol}://${req.get('host')}`,
                   description: 'Task API',
                 },
               ],
             },
             apis: ['./routes/*.js'],
           }
         )
       );
     } catch (error) {
       res.status(500).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks:
    *   get:
    *     summary: Get all tasks
    *     operationId: getAllTasks
    *     responses:
    *       200:
    *         description: List of tasks
    */
   router.get('/api/tasks', async function(req, res, next) {
     try {
       const tasks = await Task.find();
       res.json(tasks);
     } catch (error) {
       res.status(500).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks/{id}:
    *   get:
    *     summary: Get task by ID
    *     operationId: getTaskById
    *     parameters:
    *       - in: path
    *         name: id
    *         required: true
    *         schema:
    *           type: string
    *     responses:
    *       200:
    *         description: Task details
    */
   router.get('/api/tasks/:id', async function(req, res, next) {
     try {
       const task = await Task.findById(req.params.id);
       res.json(task);
     } catch (error) {
       res.status(404).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks:
    *   post:
    *     summary: Create a new task
    *     operationId: createTask
    *     requestBody:
    *       required: true
    *       content:
    *         application/json:
    *           schema:
    *             type: object
    *             properties:
    *               taskName:
    *                 type: string
    *     responses:
    *       201:
    *         description: Task created
    */
   router.post('/api/tasks', async function(req, res, next) {
     try {
       // Set createDate to current timestamp when creating a task
       const taskData = {
         ...req.body,
         createDate: new Date()
       };
   
       const task = new Task(taskData);
       await task.save();
       res.status(201).json(task);
     } catch (error) {
       res.status(400).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks/{id}:
    *   put:
    *     summary: Update a task
    *     operationId: updateTask
    *     parameters:
    *       - in: path
    *         name: id
    *         required: true
    *         schema:
    *           type: string
    *     requestBody:
    *       required: true
    *       content:
    *         application/json:
    *           schema:
    *             type: object
    *             properties:
    *               taskName:
    *                 type: string
    *               completed:
    *                 type: boolean
    *     responses:
    *       200:
    *         description: Task updated
    */
   router.put('/api/tasks/:id', async function(req, res, next) {
     try {
       // If completed is being set to true, also set completedDate
       if (req.body.completed === true) {
         req.body.completedDate = new Date();
       }
   
       const task = await Task.findByIdAndUpdate(req.params.id, req.body, { new: true });
       res.json(task);
     } catch (error) {
       res.status(400).json({ error: error.message });
     }
   });
   
   /**
    * @swagger
    * /api/tasks/{id}:
    *   delete:
    *     summary: Delete a task
    *     operationId: deleteTask
    *     parameters:
    *       - in: path
    *         name: id
    *         required: true
    *         schema:
    *           type: string
    *     responses:
    *       200:
    *         description: Task deleted
    */
   router.delete('/api/tasks/:id', async function(req, res, next) {
     try {
       const task = await Task.findByIdAndDelete(req.params.id);
       res.json({ message: 'Task deleted successfully', task });
     } catch (error) {
       res.status(404).json({ error: error.message });
     }
   });
   

   Esse código está duplicando a funcionalidade das rotas existentes, o que é desnecessário, mas você a manterá para simplificar. Uma prática recomendada seria mover a lógica do aplicativo para funções compartilhadas e chamá-las das rotas MVC e das rotas OpenAPI.

3. No terminal do codespace, execute o aplicativo com npm start.

4. Selecione Abrir no Navegador.

5. Exiba o esquema OpenAPI adicionando /schema à URL.

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

7. Depois que suas alterações forem implantadas, navegue até https://<your-app's-url>/schema 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: Sempre valide os dados de entrada para evitar entradas inválidas ou mal-intencionadas. Para aplicativos Node.js, use bibliotecas como validador expresso para impor regras de validação de dados. Consulte a documentação deles para obter melhores práticas e detalhes de implementação.
• 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?