Adicionar uma aplicação de Serviço de Aplicação como ferramenta no Foundry Agent Service (Node.js)

Neste tutorial, vais aprender a expor a funcionalidade de uma aplicação Express.js 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.

Prerequisites

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

   npm install swagger-jsdoc
   

2. Rotas abertas/index.js. Na parte inferior do arquivo, acima module.exports = router; , adicione as seguintes funções da API. Para os tornar compatíveis com o Foundry Agent Service, deve especificar a operationId propriedade na @swagger anotação ( ver Como usar o Foundry Agent Service com Ferramentas Especificadas OpenAPI: Pré-requisitos).

   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ê o manterá para simplificar. Uma prática recomendada seria mover a lógica do aplicativo para funções compartilhadas e, em seguida, chamá-las das rotas MVC e das rotas OpenAPI.

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

4. Selecione Abrirno navegador.

5. Visualize 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 executando azd up (método Azure Developer CLI).

7. Depois que as 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 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 os dados de entrada: Sempre valide os dados recebidos para evitar entradas inválidas ou maliciosas. Para aplicativos Node.js, use bibliotecas como o validador expresso para impor regras de validação de dados. Consulte a documentação para obter práticas recomendadas 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.
• 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?