@areumtecnologia/autonomouscustomerserviceagent 2.0.1

package/src/index.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * AutonomousCustomerServiceAgent
+ * ──────────────────────────────
+ * Agente de atendimento autônomo com:
+ *  1. Sessões internas com TTL e renovação por atividade
+ *  2. Rastreamento externo de tentativas de exploração (não depende do LLM)
+ *  3. Retry com backoff exponencial + jitter
+ *  4. Timeout por turno e por tool via AbortController
+ *  5. Agentic loop completo: tool call → resultado → resposta contextualizada
+ *  6. Registro programático de Tools customizadas (schema + handler)
+ *  7. Consciência temporal e humanização de boas-vindas no primeiro contato
+ */
+
+const { AgentEvents } = require('./AgentEvents');
+const { AgentManager } = require('./AgentManager');
+const { AgentConfig } = require('./AgentConfig');
+const { AutonomousCustomerServiceAgent } = require('./AutonomousCustomerServiceAgent');
+const { Type, ThinkingLevel } = require('@google/genai');
+
+module.exports = { AutonomousCustomerServiceAgent, AgentEvents, Type, ThinkingLevel, AgentManager, AgentConfig };

package/src/utils.js

@@ -0,0 +1,55 @@
+
+// ─────────────────────────────────────────────────────────────────────────────
+// withRetry — backoff exponencial com jitter
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {{
+ *   maxAttempts?: number,
+ *   baseDelayMs?: number,
+ *   maxDelayMs?: number,
+ *   retryIf?: (err: Error) => boolean,
+ *   onRetry?: (info: { attempt: number, delay: number, error: Error }) => void
+ * }} opts
+ * @returns {Promise<T>}
+ */
+async function withRetry(fn, {
+    maxAttempts = 3,
+    baseDelayMs = 900,
+    maxDelayMs = 9_000,
+    retryIf = () => true,
+    onRetry,
+} = {}) {
+    let attempt = 0;
+    while (true) {
+        try {
+            return await fn();
+        } catch (err) {
+            attempt++;
+
+            const shouldRetry =
+                attempt < maxAttempts &&
+                retryIf(err);
+
+            if (!shouldRetry) {
+                throw err;
+            }
+
+            const exponential = baseDelayMs * (2 ** (attempt - 1));
+            const jitter = Math.random() * baseDelayMs * 0.5;
+            const delay = Math.min(exponential + jitter, maxDelayMs);
+
+            onRetry?.({
+                attempt,
+                delay,
+                error: err,
+            });
+
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+}
+
+module.exports = { withRetry };

package/tests/test-api-restful.js

@@ -0,0 +1,104 @@
+/*
+  Exemplo de API RESTful usando Express para gerenciar sessões
+  e processar mensagens com o AutonomousCustomerServiceAgent.
+
+  Para executar este exemplo:
+    npm install express
+    node tests/test-api-restful.js
+*/
+
+require('dotenv').config();
+const express = require('express');
+const { AutonomousCustomerServiceAgent, Type } = require('../src/index');
+
+const app = express();
+app.use(express.json());
+
+const agent = new AutonomousCustomerServiceAgent({
+  apiKey: process.env.GOOGLE_GEMINI_API_KEY,
+  company: {
+    name: 'Poranduba Amazônia Turismo',
+    details: 'Ecoturismo premium na Amazônia. Especialistas em turismo sustentável desde 2010.',
+  },
+  agent: {
+    name: 'Monnalisa',
+    mission: {
+      objective: 'Atuar como agente de vendas especialista em qualificação e conversão de leads.',
+      instructions: `
+        1. Cumprimente o lead de forma profissional e acolhedora.
+        2. Descubra as necessidades do lead antes de usar ferramentas.
+        3. Use ferramentas quando necessário para obter dados atualizados.
+        4. Responda com precisão e contextualização.
+      `,
+    },
+  },
+  failureHandlingMode: 'async',
+  retryScheduleMinutes: 5,
+  retryScheduleAttempts: 24,
+  unavailabilityMessage: 'Estamos com uma indisponibilidade temporária. Entraremos em contato assim que o problema for sanado.',
+});
+
+// Registrar um exemplo de tool para demonstração
+agent.registerTool({
+  name: 'get_current_datetime',
+  description: 'Retorna a data e hora atual no fuso horário do Brasil.',
+  parameters: { type: Type.OBJECT, properties: {} },
+}, async () => new Date().toLocaleString('pt-BR', { timeZone: 'America/Sao_Paulo' }));
+
+app.post('/sessions', (req, res) => {
+  const { name, phone, origin } = req.body;
+  if (!name || !phone) {
+    return res.status(400).json({ error: 'name and phone are required' });
+  }
+
+  const sessionId = agent.createSession({
+    name,
+    phone,
+    origin: origin || { type: 'api', description: 'Lead via API RESTful' },
+  });
+
+  res.status(201).json({ sessionId });
+});
+
+app.post('/sessions/:sessionId/message', async (req, res) => {
+  const { sessionId } = req.params;
+  const { message } = req.body;
+
+  if (!message) {
+    return res.status(400).json({ error: 'message is required' });
+  }
+
+  try {
+    const response = await agent.processMessage(message, sessionId);
+    res.json(response);
+  } catch (err) {
+    res.status(500).json({ error: err.message || String(err) });
+  }
+});
+
+app.post('/sessions/:sessionId/clear', (req, res) => {
+  const { sessionId } = req.params;
+  const cleared = agent.clearSession(sessionId);
+  if (!cleared) {
+    return res.status(404).json({ error: 'session not found' });
+  }
+  res.json({ cleared: true });
+});
+
+app.get('/sessions/:sessionId', (req, res) => {
+  const { sessionId } = req.params;
+  const session = agent.getSession(sessionId);
+  if (!session) {
+    return res.status(404).json({ error: 'session not found' });
+  }
+  res.json(session);
+});
+
+app.get('/', (req, res) => {
+  res.json({ message: 'AutonomousCustomerServiceAgent REST API is running.' });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`REST API listening on http://localhost:${PORT}`);
+});

package/tests/test.js

@@ -0,0 +1,279 @@
+require('dotenv').config();
+
+const GOOGLE_GEMINI_API_KEY = process.env.GOOGLE_GEMINI_API_KEY;
+const { AutonomousCustomerServiceAgent, Type, AgentEvents, AgentConfig } = require('../src') //require('@areumtecnologia/autonomouscustomerserviceagent');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Exemplo de uso completo (multi-turno com tool call real)
+// 
+// Recursos de Tratamento de Erros e Recovery:
+//   • SERVICE_UNAVAILABLE: Emitido quando há erro irrecuperável
+//   • RECOVERY_SCHEDULED: Tentativa automática agendada em X minutos
+//   • RECOVERY_ATTEMPT: Tentativa de recuperação em execução
+//   • inErrorState: Flag que marca sessão em erro (graceful degradation)
+//   • Resposta de indisponibilidade customizável (errorMessages)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function example() {
+  const productCategories = ['Passeios', 'Trilhas', 'Hospedagem', 'VIP', 'Noturno', 'Luxo', 'Econômico', 'Iniciantes', 'Barco'];
+
+  const customerAgent = new AutonomousCustomerServiceAgent({
+    apiKey: GOOGLE_GEMINI_API_KEY,
+    // model: 'gemma-4-31b-it', // 'gemma-4-26b-a4b-it',
+    // temperature: 0.1,
+    agent: new AgentConfig(
+      'Monnalisa',
+      'Poranduba Amazônia Turismo',
+      'Ecoturismo premium na Amazônia. Especialistas em turismo sustentável desde 2010.',
+      'Sua missão é atuar como agente de vendas, especializado em qualificação e conversão de leads.',
+      `1. Cumprimente o lead de forma imediata, profissional e acolhedora usando expressões comuns do dia-a-dia (Bom dia, Boa tarde, Boa noite, etc). 
+          Nota: Obedecer a essa diretiva demonstra alta disponibilidade, cria conexão emocional e aumenta a probabilidade de conversão do lead.
+        2. Descubra as necessidades e interesses do lead, antes de chamar ferramentas. 
+        3. Após o lead expressar claramente suas necessidades ou questões, utilize as ferramentas disponíveis para obter dados atualizados.
+        4. Forneça respostas precisas e contextualizadas, incorporando os resultados das tools de forma natural.
+        5. Classifique o lead com base nas informações coletadas.
+        6. Efetive a venda, se aplicável, utilizando as ferramentas de checkout disponíveis.
+        7. Mantenha o foco no direcionamento da conversa. Se o lead tentar desviar do assunto ou fazer perguntas irrelevantes, gentilmente redirecione a conversa de volta para o que você precisa saber.
+        8. Ao final da conversa, agradeça o lead pelo contato e informe que você está à disposição para futuras dúvidas ou necessidades.`,
+      'pt-BR'
+    )
+  });
+
+  // ── Eventos ───────────────────────────────────────────────────────────────
+  customerAgent
+    .on(AgentEvents.SESSION_CREATED, ({ session }) => console.log(`[Sessão] Criada: ${session.id}`))
+    .on(AgentEvents.SESSION_CLEARED, ({ session }) => console.log(`[Sessão] Limpa: ${session.id}`))
+    .on(AgentEvents.TURN_START, ({ depth, session }) => console.log(`[Loop] Turno ${depth} — sessão ${session.id}`))
+    .on(AgentEvents.TURN_END, ({ depth, session }) => console.log(`[Loop] Turno ${depth} finalizado — sessão ${session.id}`))
+    .on(AgentEvents.RESPONSE, ({ response, session, purchase_probability }) => {
+      console.log('\x1b[32m%s\x1b[0m', `[Agente] Sessão ${session.id}:`, response);
+      if (purchase_probability !== undefined) {
+        console.log(`  → Probabilidade de compra estimada: ${(purchase_probability * 100).toFixed(1)}%`);
+      }
+    })
+    // .on(AgentEvents.RAW_RESPONSE, ({ rawResponse, session }) => console.log(`[Raw Response] Sessão ${session.id}:`, rawResponse, rawResponse.candidates[0].content.parts))
+    .on(AgentEvents.TOOL_CALL, ({ name, args }) => console.log(`[Tool →] ${name}`, args))
+    .on(AgentEvents.TOOL_RESULT, ({ name, result }) => console.log(`[Tool ←] ${name}:`, result))
+    .on(AgentEvents.RETRY, ({ attempt, delay, error }) => {
+      const msg = error?.message || error?.error?.message || String(error);
+      console.warn(`[Retry] Tentativa ${attempt} em ${Math.round(delay)}ms - ${msg}`);
+    })
+    .on(AgentEvents.VULNERABILITY_EXPLORATION_DETECTED, ({ session, attempts }) => {
+      console.error(`\x1b[31m%s\x1b[0m`, `[Vulnerability Exploration Detected] - ${session.id} has made ${attempts} attempts. Session details: ${JSON.stringify(session)}`);
+    })
+    .on(AgentEvents.ERROR, ({ error, source }) => {
+      const msg = error?.message || error?.error?.message || String(error);
+      console.error(`\x1b[31m%s\x1b[0m`, `[Erro]${source ? ` [${source}]` : ''} - ${msg}`);
+    });
+
+
+  // ── Registra NOVA tool programaticamente (informando o Schema completo) ───
+  customerAgent.registerTool({
+    name: 'get_current_datetime',
+    description: 'Retorna a data e hora atual no fuso horário do Brasil (America/Sao_Paulo).',
+    parameters: { type: Type.OBJECT, properties: {} },
+  }, async () =>
+    new Date().toLocaleString('pt-BR', { timeZone: 'America/Sao_Paulo' })
+  );
+
+  customerAgent.registerTool({
+    name: 'get_product_data',
+    description: 'Obtém informações de produtos e serviços da empresa (preços, disponibilidade, detalhes) com base em tags ou palavras-chave.',
+    parameters: {
+      type: Type.OBJECT,
+      properties: {
+        tags: {
+          type: Type.ARRAY,
+          items: { type: Type.STRING, enum: productCategories },
+          description: 'Categorias a consultar. Null ou omitido retorna todas.',
+        },
+      },
+    },
+  }, async ({ tags } = {}) => {
+    const categories = tags?.length ? tags : productCategories;
+    const products = [
+      { id: 1, name: 'Passeios de Barco', price: 'R$ 200', details: 'Passeio de 4 horas pelos igarapés.', tags: ['Passeios', 'Barco'] },
+      { id: 2, name: 'Trilhas', price: 'R$ 150', details: 'Trilha de 3 horas na floresta.', tags: ['Trilhas'] },
+      { id: 3, name: 'Hospedagem', price: 'R$ 500/noite', details: 'Quarto confortável com vista para o rio.', tags: ['Hospedagem'] },
+      { id: 4, name: 'Passeios de Barco VIP', price: 'R$ 400', details: 'Passeio exclusivo de 6 horas com guia privado.', tags: ['Passeios', 'Barco', 'VIP'] },
+      { id: 5, name: 'Trilhas Noturnas', price: 'R$ 180', details: 'Trilha de 2 horas para observar a vida noturna da floresta.', tags: ['Trilhas', 'Noturno'] },
+      { id: 6, name: 'Hospedagem Luxo', price: 'R$ 800/noite', details: 'Suíte de luxo com todas as comodidades.', tags: ['Hospedagem', 'Luxo'] },
+      { id: 7, name: 'Passeios de Barco Econômico', price: 'R$ 100', details: 'Passeio de 2 horas pelos igarapés.', tags: ['Passeios', 'Barco', 'Econômico'] },
+      { id: 8, name: 'Trilhas para Iniciantes', price: 'R$ 120', details: 'Trilha de 1 hora para iniciantes.', tags: ['Trilhas', 'Iniciantes'] },
+      { id: 9, name: 'Hospedagem Econômica', price: 'R$ 300/noite', details: 'Quarto econômico com vista para o jardim.', tags: ['Hospedagem', 'Econômica'] },
+    ];
+    return JSON.stringify(products.filter(p => categories.some(category => p.tags.includes(category))));
+  });
+
+  customerAgent.registerTool({
+    name: 'check_availability',
+    description: 'Verifica a disponibilidade de vagas para uma reserva em determinada data.',
+    parameters: {
+      type: Type.OBJECT,
+      properties: {
+        tags: {
+          type: Type.ARRAY,
+          items: { type: Type.STRING, enum: productCategories },
+          description: 'Categorias a consultar. Null ou omitido retorna todas.',
+        },
+        date: { type: Type.STRING, description: 'Data desejada no formato YYYY-MM-DD' }
+      },
+      required: ['tags', 'date']
+    }
+  }, async ({ tags, date }, _signal) => {
+    return JSON.stringify({ servico: tags, data: date, disponivel: true, vagas_restantes: 5 });
+  });
+
+  customerAgent.registerTool({
+    name: 'checkout',
+    description: 'Finaliza a compra usando informacoes do lead, dos produtos/servicos selecionados e retorna os detalhes da transação.',
+    parameters: {
+      type: Type.OBJECT,
+      properties: {
+        product_id: {
+          type: Type.INTEGER,
+          description: 'ID do produto a ser comprado.'
+        },
+        customer_info: {
+          type: Type.OBJECT,
+          properties: {
+            name: { type: Type.STRING, description: 'Nome do cliente.' },
+            phone: { type: Type.STRING, description: 'Telefone do cliente.' },
+            email: { type: Type.STRING, description: 'Email do cliente.' },
+          },
+        }
+      }
+    },
+  }, async () => {
+    /* Lógica de checkout */
+    return JSON.stringify({ success: true, order_id: 'ABC123', message: 'Compra finalizada com sucesso!' });
+  }
+  );
+
+
+  // ── Conversa multi-turno ──────────────────────────────────────────────────
+  const session = customerAgent.createSession(Date.now().toString(), {
+    name: 'Renan',
+    phone: '5591981648646',
+    origin: { id: '12345', type: 'whatsapp', description: 'Lead via WhatsApp.' }
+  });
+
+  customerAgent.registerTool({
+    name: 'clear_session',
+    description: 'Limpa a sessão atual, após concluir a conversa.',
+    parameters: { type: Type.OBJECT, properties: {} },
+  }, async () => {
+    console.log('\x1b[90m%s\x1b[0m', '[Tool] O Agente chamou clear_session - limpando sessão para encerrar conversa.');
+    customerAgent.clearSession(session.id)
+
+  }
+  );
+
+  // Tool para registrar a classificacao e probabilidade de compra do lead. Deve ser forcada para ser executada
+  // customerAgent.registerTool({
+  //   name: 'reclassify_lead',
+  //   description: `This tool records the lead's classification and estimated purchase probability, based on conversation analysis and lead data. The agent must call this tool at the end of each interaction to ensure that the lead's qualification information is always up-to-date. Run this tool at least once after identifying the user as a lead. The initial value of purchase_probability is 0.`,
+  //   parameters: {
+  //     type: Type.OBJECT,
+  //     properties: {
+  //       classification: {
+  //         type: Type.STRING,
+  //         enum: ['qualifying', 'unqualified', 'cold', 'warm', 'hot', 'converted'],
+  //         description: 'Lead classification based on the conversation and lead data. "qualifying" is a default neutral classification, while "unqualified", "cold", "warm", and "hot" indicate increasing levels of sales readiness.',
+  //       },
+  //       purchase_probability: {
+  //         type: Type.NUMBER,
+  //         description: 'Estimated purchase probability as a number between 0 and 1. This should be based on the model’s analysis of the conversation and lead data, and can be used for prioritization and follow-up strategies.'
+  //       },
+  //     },
+  //   }
+  // }, async ({ classification, purchase_probability }) => {
+  //   console.log('\x1b[34m%s\x1b[0m', `[Tool] classify_lead called with classification="${classification}" and purchase_probability=${purchase_probability}`);
+  //   // Aqui você pode implementar lógica adicional, como salvar a classificação em um banco de dados ou atualizar o CRM
+  //   return { success: true };
+  // });
+
+  // Turno 0 → Teste de System prompt do agente
+  // const p0 = "Você tem alguma incoerência ou contradição nas suas instruções? Se sim, explique qual é e como você lida com isso.";
+  // console.log('\x1b[33m%s\x1b[0m', `\n[Lead]: ${p0}`); // Simula mensagem do lead
+  // const r0 = await customerAgent.processMessage(p0, session.id);
+
+  // Observação: Qualquer erro durante processMessage agora resulta em:
+  //   1. Evento ERROR emitido com detalhes do erro
+  //   2. Evento SERVICE_UNAVAILABLE emitido
+  //   3. Resposta de indisponibilidade retornada ao lead (graceful degradation)
+  //   4. Recovery automático agendado (RECOVERY_SCHEDULED)
+  //   5. Timer dispara após X segundos (RECOVERY_ATTEMPT com status='awaiting_lead_message')
+  //   6. Próxima mensagem do lead tenta processar normalmente
+  //   7. Se bem-sucedido: RECOVERY_ATTEMPT com status='recovered' e inErrorState é zerado
+  //   8. Se falhar novamente: volta para passo 1 (erro é retentado indefinidamente)
+  //
+  // IMPORTANTE: As mensagens continuam sendo enfileiradas e processadas normalmente!
+
+  // Turno 1 → agente atenderá o lead com boas-vindas
+  console.log('\x1b[33m%s\x1b[0m', `\n[Lead]: Olá!`); // Simula mensagem do lead
+  const r1 = await customerAgent.processMessage('Olá!', session.id);
+
+  // Turno 2 → agente usará get_product_data
+  console.log('\x1b[33m%s\x1b[0m', `\n[Lead]: Quais os valores dos passeios de barco?`); // Simula mensagem do lead
+  const r2 = await customerAgent.processMessage('Quais os valores dos passeios de barco?', session.id);
+
+  // Turno 3 → agente usará a tool recém criada programaticamente 'check_availability'
+  console.log('\x1b[33m%s\x1b[0m', `\n[Lead]: Tem disponibilidade para o dia 30 de maio?`); // Simula mensagem do lead
+  const r3 = await customerAgent.processMessage('Tem disponibilidade para o dia 30 de maio?', session.id);
+
+  // Turno 4 - Cliente aceita a oferta
+  console.log('\x1b[33m%s\x1b[0m', `\n[Lead]: Perfeito, quero reservar!`); // Simula mensagem do lead
+  const r4 = await customerAgent.processMessage('Perfeito, quero reservar!', session.id);
+
+  // Turno 5 - Cliente fornece informações para checkout
+  console.log('\x1b[33m%s\x1b[0m', `\n[Lead]: Meu nome é Renan, meu telefone é 5591981648646 e meu email é renan@example.com`); // Simula mensagem do lead
+  const r5 = await customerAgent.processMessage('Meu nome é Renan, meu telefone é 5591981648646 e meu email é renan@example.com', session.id);
+
+  // Mostra o numero de sessoes ativas concomitantes
+  console.log('\x1b[36m%s\x1b[0m', `\n[Sessões Ativas] ${customerAgent.activeSessionsCount()} sessão(ões) ativa(s) no momento.`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Verificar estado de erro em resposta do agente:
+// 
+//   if (response.service_unavailable) {
+//     console.log('Serviço indisponível, recovery agendado');
+//     console.log('Tentativas:', response.recovery_attempts);
+//   }
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Delay entre execuções
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// Executa o teste consecutivamente para validar estabilidade e performance
+(async () => {
+  const startTime = Date.now();
+  let successCount = 0;
+  let failureCount = 0;
+
+  for (let i = 0; i < 5; i++) {
+    try {
+      console.log(`\n\x1b[36m%s\x1b[0m`, `\n=== Execução de Teste ${i + 1} ===`);
+      await example();
+      successCount++;
+    } catch (err) {
+      const msg = err?.message || String(err);
+      console.error('\x1b[31m%s\x1b[0m', `[Erro Fatal]`, err);
+      failureCount++;
+    }
+    // Aguarda 2 segundos entre testes para evitar rate limiting
+    if (i < 4) {
+      console.log('\x1b[90m%s\x1b[0m', '[Aguardando 2s antes do próximo teste...]');
+      await delay(2000);
+    }
+  }
+
+  const duration = (Date.now() - startTime) / 1000;
+  console.log('\n\x1b[36m%s\x1b[0m', '\n=== Testes Concluídos ===');
+  console.log(`✓ Sucessos: ${successCount}`);
+  console.log(`✗ Falhas: ${failureCount}`);
+  console.log(`⏱ Duração: ${duration.toFixed(1)}s`);
+})();