{"_id":"@areumtecnologia/agentic-core","_rev":"7-994a42fbcbb753d09bc75f8cf1c76eb4","name":"@areumtecnologia/agentic-core","dist-tags":{"latest":"3.3.2"},"versions":{"3.0.0":{"name":"@areumtecnologia/agentic-core","version":"3.0.0","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"author":{"name":"Áreum Tecnologia"},"license":"ISC","_id":"@areumtecnologia/agentic-core@3.0.0","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"dist":{"shasum":"491e4d4b65418abc51479730b3652311ca78817e","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.0.0.tgz","fileCount":35,"integrity":"sha512-9CaechnQfH/IMo9Demmufce3rQEx3//5eGs6Ab13fCyK4+srVBRsGC2XUgML1DLalS/lwUqkUw/HhW5q9/8swA==","signatures":[{"sig":"MEQCIQDP0twa9gN9HxEVn2eFWxj6ff71mDQHOz0MSItOqX4w9AIffJsO7zz1xvgvcIrrByssQMC/7Oj0yk93pqHZEtLArw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":243334},"main":"src/index.js","type":"commonjs","engines":{"node":">=16.0.0"},"gitHead":"a7db374ec72638be83db53cabee702f10adac52b","scripts":{"test":"node tests/test.js","start":"node tests/test.js"},"_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), failover automático, sessões com TTL, concorrência temporal e integração nativa ao protocolo MCP.","directories":{"test":"tests"},"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","@google/genai":"^2.9.0"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"tmp":"tmp/agentic-core_3.0.0_1782397865416_0.9963338030050999","host":"s3://npm-registry-packages-npm-production"}},"3.0.1":{"name":"@areumtecnologia/agentic-core","version":"3.0.1","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"author":{"name":"Áreum Tecnologia"},"license":"ISC","_id":"@areumtecnologia/agentic-core@3.0.1","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"dist":{"shasum":"d8957d91c4b18d99b9db0e7e922b1cc406a99fab","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.0.1.tgz","fileCount":36,"integrity":"sha512-S/QGSbSi8vXy2DX4SDGXDKRm9lB0RmzIDtOQd6vrTgKLWYkwGZicxxIu+DBPXKkK+3kAMuitrzIpoZfmFNw4FA==","signatures":[{"sig":"MEQCIHq10sIGAjaOSfJYRSuvc1iACXrV0oITqcGIneanKsREAiBIJ8mU9ION8t0j/U0dyUMjLzCr8kgJEqoO4v0JJFtgsA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":244757},"main":"src/index.js","type":"commonjs","engines":{"node":">=16.0.0"},"gitHead":"092b21f6d81b63d54888eaf5230a283fab2b2148","scripts":{"test":"node tests/test.js","start":"node tests/test.js"},"_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), failover automático, sessões com TTL, concorrência temporal e integração nativa ao protocolo MCP.","directories":{"test":"tests"},"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","@google/genai":"^2.9.0"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"tmp":"tmp/agentic-core_3.0.1_1782430947513_0.6282805421873299","host":"s3://npm-registry-packages-npm-production"}},"3.1.0":{"name":"@areumtecnologia/agentic-core","version":"3.1.0","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"author":{"name":"Áreum Tecnologia"},"license":"ISC","_id":"@areumtecnologia/agentic-core@3.1.0","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"dist":{"shasum":"a7bd34fb813703ce198e0f124e9657ddddf0e13b","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.1.0.tgz","fileCount":59,"integrity":"sha512-rKGLlbCqySWY4ZEHbqhiuaDVOoPeV8Y4UjHOIlo4FmzokA6wz2pzjmv4TF0VINhWMd9PlJuO0O3EVcx0D1k1Aw==","signatures":[{"sig":"MEQCIAsCXJG101Zi6Vt3kAe0pQjqeTFEYCFBBhsaeIyq2xEjAiBcTTBWvByhvDk1edhgT9LRdO2F62P3vvbfHcdztZ1sDg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":296990},"main":"src/index.js","type":"commonjs","engines":{"node":">=16.0.0"},"gitHead":"77de4753b9b271eda0ae485efeb43d0d66bce142","scripts":{"test":"node tests/test.js","start":"node tests/test.js"},"_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), failover automático, sessões com TTL, concorrência temporal e integração nativa ao protocolo MCP.","directories":{"test":"tests"},"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","openai":"^6.49.0","@google/genai":"^2.9.0","fluent-ffmpeg":"^2.1.3"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"tmp":"tmp/agentic-core_3.1.0_1785806337317_0.5086570216178781","host":"s3://npm-registry-packages-npm-production"}},"3.1.1":{"name":"@areumtecnologia/agentic-core","version":"3.1.1","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"author":{"name":"Áreum Tecnologia"},"license":"ISC","_id":"@areumtecnologia/agentic-core@3.1.1","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"dist":{"shasum":"13996e12eabeb30576bf01dea7cb2467a9eb412c","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.1.1.tgz","fileCount":59,"integrity":"sha512-6365zzgchE7+E9B8jzZP2gxFP4oInpepDAfFzS9cTpgIi77oYpCiLz1rEVqmLJn/Aa9yOZGZEWvt4l2PHP5mJg==","signatures":[{"sig":"MEQCIGQqKwUfTMEoAgsg3OFGl2rYhO55q3WI6HNwJANCXlw8AiAKFb+eJNZF2EI/A/SAzQmadODJA1kW7NOF1G0p8x/HYg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":297234},"main":"src/index.js","type":"commonjs","engines":{"node":">=16.0.0"},"gitHead":"2779f561d2cce4eb823d8fd475d0fc26075939eb","scripts":{"test":"node tests/test.js","start":"node tests/test.js"},"_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), failover automático, sessões com TTL, concorrência temporal e integração nativa ao protocolo MCP.","directories":{"test":"tests"},"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","openai":"^6.49.0","@google/genai":"^2.9.0","fluent-ffmpeg":"^2.1.3"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"tmp":"tmp/agentic-core_3.1.1_1785876564109_0.613003237405906","host":"s3://npm-registry-packages-npm-production"}},"3.2.0":{"name":"@areumtecnologia/agentic-core","version":"3.2.0","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"author":{"name":"Áreum Tecnologia"},"license":"ISC","_id":"@areumtecnologia/agentic-core@3.2.0","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"dist":{"shasum":"bc6b58e35f0f7d543ceeaec3507ed0813911fbdf","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.2.0.tgz","fileCount":64,"integrity":"sha512-OW+6kFDKN/iLhZSZFKgXMv7sCatgVOl/41zdHjL8Toj6x1KyE9Xjd9JQcnKJRmw53iIuKZ4D9dN1qn6ey5K9oA==","signatures":[{"sig":"MEUCIBnpS2LAZHj0vlLafMI+Q+1KZib2BxERUqIfWksFaiyZAiEAwmkDtiGLKHzaj+R/jLDeACvWDR7Y4W6uR5sJaih5LJ8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":344203},"main":"src/index.js","type":"commonjs","engines":{"node":">=18.0.0"},"gitHead":"b6fe058c81e075f7509692667b210863adcb78d0","scripts":{"test":"node tests/test.js","start":"node tests/test.js"},"_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), failover automático, sessões com TTL, concorrência temporal e integração nativa ao protocolo MCP.","directories":{"test":"tests"},"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","axios":"^1.19.0","openai":"^6.49.0","@google/genai":"^2.9.0","fluent-ffmpeg":"^2.1.3"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"tmp":"tmp/agentic-core_3.2.0_1787410521440_0.7159703920997604","host":"s3://npm-registry-packages-npm-production"}},"3.3.1":{"name":"@areumtecnologia/agentic-core","version":"3.3.1","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"author":{"name":"Áreum Tecnologia"},"license":"ISC","_id":"@areumtecnologia/agentic-core@3.3.1","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"dist":{"shasum":"58f462558ec3231b9ab7d4a4b5561655355d3f8a","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.3.1.tgz","fileCount":74,"integrity":"sha512-agW+qIV3IKbZzP4nGWUDwAE0Kp+Scnn+UxKEXzf/3mws4BJKIUOmzjLnAXCdHUCgzEUt5cTe+cy4rMDZ/gkFIw==","signatures":[{"sig":"MEQCICYWQWvq81Ou4exwgGJTXP5QIH4FFvQn2pRBB50wg5bgAiAURvEbkHbyS2ZlqYX/HKnZ/LQnaDWNHzCntrSm99VzUA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIEycCroCilPYZ6DZAC2CGfTfC9JGXO1pZL5IhDy5fvNjAiBB+hPr+94L65uiQQ8nF7vnY0AsTSAXfceNIDT5JPjmiw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":429322},"main":"src/index.js","type":"commonjs","engines":{"node":">=18.0.0"},"gitHead":"b6fe058c81e075f7509692667b210863adcb78d0","scripts":{"test":"node tests/test_code_review_fixes.js && node tests/test_evolution_v33.js && node tests/test_reasoning_tool.js && node tests/test_math_tool.js && node tests/test_web_search_tool.js","start":"node tests/test.js","test:web":"node tests/test_web_search_tool.js","test:math":"node tests/test_math_tool.js","test:evolution":"node tests/test_evolution_v33.js","test:reasoning":"node tests/test_reasoning_tool.js"},"_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), streaming em tempo real, auto-RAG de memória, políticas de segurança, failover automático e telemetria nativa.","directories":{"test":"tests"},"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","axios":"^1.19.0","openai":"^6.49.0","@google/genai":"^2.9.0","fluent-ffmpeg":"^2.1.3"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"tmp":"tmp/agentic-core_3.3.1_1790055833758_0.7801211123768579","host":"s3://npm-registry-packages-npm-production"}},"3.3.2":{"_id":"@areumtecnologia/agentic-core@3.3.2","dist":{"shasum":"d47062fb9d4c61f5f7e8e7a0bce8c2dbcd5ffee1","tarball":"https://registry.npmjs.org/@areumtecnologia/agentic-core/-/agentic-core-3.3.2.tgz","fileCount":74,"integrity":"sha512-TiEHZ5orJzjGmLYV784YRQ9jYS8BEX2yDG395QuWtRd+V+GTV3eLAOkZZvFRlOWwy+yTymeZa65bJQt337X27Q==","signatures":[{"sig":"MEYCIQCb6Db2Lquv0fSrH7TO2Svc+yd4qHNCzUuRTa3xCKmPEQIhANTR1qxcCGAX5MXy64Vw7MTU3JfhYBjy+A2U4/8Rysf0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGdfhodE83kOdEHUNtgWjLEEqA+2WBMceOQ6AzUPIS9NAiAXSO/xJMWp1VBXwbPKwMfVT9bLpSovj7qcqKkoMxgrWA=="}],"unpackedSize":435015},"main":"src/index.js","name":"@areumtecnologia/agentic-core","type":"commonjs","author":{"name":"Áreum Tecnologia"},"engines":{"node":">=18.0.0"},"gitHead":"b6fe058c81e075f7509692667b210863adcb78d0","license":"ISC","scripts":{"test":"node tests/test_code_review_fixes.js && node tests/test_evolution_v33.js && node tests/test_reasoning_tool.js && node tests/test_math_tool.js && node tests/test_web_search_tool.js","start":"node tests/test.js","test:web":"node tests/test_web_search_tool.js","test:math":"node tests/test_math_tool.js","test:evolution":"node tests/test_evolution_v33.js","test:reasoning":"node tests/test_reasoning_tool.js"},"version":"3.3.2","_npmUser":{"name":"areumtecnologia","email":"dev@areum.com.br"},"keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"_npmVersion":"11.6.0","description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), streaming em tempo real, auto-RAG de memória, políticas de segurança, failover automático e telemetria nativa.","directories":{"test":"tests"},"maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"_nodeVersion":"25.2.1","dependencies":{"uuid":"^14.0.0","axios":"^1.19.0","openai":"^6.49.0","@google/genai":"^2.9.0","fluent-ffmpeg":"^2.1.3"},"_hasShrinkwrap":false,"devDependencies":{"dotenv":"^17.4.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentic-core_3.3.2_1790056371479_0.5378220576607955"}}},"time":{"created":"2026-06-25T14:31:05.271Z","modified":"2026-09-22T05:52:51.773Z","3.0.0":"2026-06-25T14:31:05.578Z","3.0.1":"2026-06-25T23:42:27.661Z","3.1.0":"2026-08-04T01:18:57.462Z","3.1.1":"2026-08-04T20:49:24.259Z","3.2.0":"2026-08-22T14:55:21.667Z","3.3.1":"2026-09-22T05:43:53.844Z","3.3.2":"2026-09-22T05:52:51.629Z"},"author":{"name":"Áreum Tecnologia"},"license":"ISC","keywords":["ai","customer-service","chatbot","google-gemini","agent","agentic-loop","autonomous"],"description":"Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte multi-provedor (Gemini, OpenAI, Anthropic, Ollama, Nvidia), streaming em tempo real, auto-RAG de memória, políticas de segurança, failover automático e telemetria nativa.","maintainers":[{"name":"areumtecnologia","email":"dev@areum.com.br"}],"readme":"# Agentic Core\n\n> **v3.3.1** — Framework profissional para orquestração de Agentes Autônomos em Node.js com suporte a múltiplos provedores redundantes (Google Gemini, OpenAI, Claude, Ollama, Nvidia), **ferramentas nativas de raciocínio passo a passo (`reasoningTool`)**, **cálculo determinístico em sandbox segura (`calculatorTool`)**, **pesquisa web gratuita e sem API keys (`webSearchTool`)**, **streaming em tempo real com `TokenStream`**, **auto-RAG de memória com `ContextAugmenter`**, **segurança avançada com `ToolSecurityPolicy`, anti-SSRF e path confinement**, **orquestração em DAG condicional**, observabilidade e telemetria com `TelemetryProvider`, suporte nativo ao protocolo MCP (Model Context Protocol), failover automático em falhas 5xx, suporte a mídias multimodais e concorrência transparente.\n\n---\n\n## ✨ Características\n\n| Recurso | Descrição |\n|---|---|\n| **Raciocínio Passo a Passo (v3.3.1)** | `reasoningTool: true` ativa a ferramenta de *Sequential Thinking* (`record_thought_step`). O agente decompõe problemas complexos em etapas, hipóteses e revisões com emissão de eventos `AgentEvents.REASONING_CHUNK`. |\n| **Cálculo Determinístico PAL (v3.3.1)** | `calculatorTool: true` (ou `mathTool`) disponibiliza a ferramenta `calculate_expression`. Avalia expressões matemáticas em sandbox isolada `node:vm` protegida contra RCE com timeout de 1.500ms e precisão exata. |\n| **Pesquisa Web Nativa e Gratuita (v3.3.1)** | `webSearchTool: true` (ou `searchTool`) fornece a ferramenta `web_search`. Realiza buscas em tempo real na internet via DuckDuckGo sem chaves de API, com extração limpa de snippets e proteção anti-SSRF. |\n| **Compatibilidade com SLMs (v3.3.1)** | Roteamento inteligente de intenção e parser resiliente de chamadas XML/JSON, garantindo **100% de precisão de acerto** comprovado em modelos ultracompactos locais como **`qwen3:0.6b`**. |\n| **Streaming & Realtime (v3.3)** | `processMessageStream()` e `TokenStream` com suporte a `for await (const chunk of stream)` e eventos para tokens parciais, raciocínio (`thought`), chamadas e retornos de ferramentas. |\n| **Auto-RAG de Memória (v3.3)** | `ContextAugmenter` para recuperação e injeção automática de fatos duradouros e episódios passados no contexto do agente (`autoRetrieveMemory: true`). |\n| **Segurança & Sandboxing (v3.3)** | `ToolSecurityPolicy` com rate limiting por sessão, listas de bloqueio/permissão de ferramentas, proteção anti-SSRF em `WebTools` e confinamento de caminho contra path traversal em `FileTools`. |\n| **DAG Condicional & Reativo (v3.3)** | `TaskGraph` e `ParallelExecutor` com suporte a branches condicionais (`condition`), transformação de contexto entre nós (`transformContext`) e tarefas via funções diretas (`fn`). |\n| **Telemetria & Observabilidade (v3.3)** | `TelemetryProvider` com rastreamento hierárquico de spans (`startSpan`/`endSpan`), latência (`durationMs`), status e contabilidade acumulada de tokens (`prompt`, `completion`, `total`). |\n| **Multi-Provider Nativo** | Suporte a **Google Gemini**, **OpenAI GPT**, **Anthropic Claude**, **Ollama** (modelos locais) e **Nvidia NIM**. |\n| **Redundância e Failover** | Múltiplos modelos/provedores com `currentIndex` atômico. Transição imediata em falhas 5xx, rate limits ou timeouts. |\n| **Suporte Nativo a MCP** | Integração completa com o protocolo MCP (Model Context Protocol), atuando tanto como Cliente MCP quanto Servidor MCP via Stdio/SSE. |\n| **Memória Hierárquica** | `WorkingMemory` (janela deslizante), `ContextCompactor` (resumos via LLM), `EpisodicMemory` (episódios significativos) e `SemanticMemory` (fatos e preferências). |\n| **SubAgentes Isolados** | `SubAgent` para execução de tarefas especializadas em segundo plano, com gestão efêmera de sessão e desregistro automático de ferramentas temporárias. |\n| **Plataforma Multi-Tenant** | `PlatformManager` para gestão de múltiplos tenants, agentes e sessões isoladas. |\n| **Persistência de Sessões** | `SessionStore` e `InMemorySessionStore` para salvamento, restauração e exclusão persistente de estado. |\n| **Suporte Multimídia** | Envio de anexos (imagens, áudio, vídeo, PDFs) em Base64 no processamento de mensagens. |\n| **Concorrência Transparente** | Gerenciamento automático de mensagens consecutivas (`debounceMs`) com cancelamento ativo no LLM. |\n| **Agentic Loop Completo** | Tool calls encadeados com execução recursiva e contextualizada. |\n| **Gerenciamento de Sessões** | TTL configurável com renovação automática por atividade e normalização transparente de chaves (string/número). |\n| **Sistema de Ferramentas** | **18+ ferramentas embutidas** organizadas em categorias (reasoning, web, file, database, system, communication) com validação de schema, composição, chaining e marketplace. |\n\n---\n\n## 📦 Instalação\n\n### Via npm (Registro Público Oficial)\n\n```bash\nnpm install @areumtecnologia/agentic-core\n```\n\n### Via GitHub Packages\n\n```bash\nnpm install github:areumtecnologia/agentic-core\n```\n\n### Via clone local\n\n```bash\ngit clone https://github.com/areumtecnologia/agentic-core.git\ncd agentic-core\nnpm install\n```\n\n### Pré-requisitos\n\n- Node.js `>=18.0.0`\n- Chave de API de um provedor compatível (Google Gemini, OpenAI, Anthropic, Nvidia) ou Ollama rodando localmente\n\n---\n\n## ⚙️ Configuração\n\nCopie o arquivo de exemplo e configure suas credenciais:\n\n```bash\ncp .env.example .env\n```\n\n```env\n# .env\nGOOGLE_GEMINI_API_KEY=sua-chave-aqui\nOPENAI_API_KEY=sua-chave-openai-aqui\nANTHROPIC_API_KEY=sua-chave-anthropic-aqui\nNVIDIA_API_KEY=sua-chave-nvidia-aqui\n```\n\n---\n\n## 🚀 Quickstart\n\n### Exemplo Básico com Google Gemini\n\n```javascript\nrequire('dotenv').config();\nconst { \n  AgenticCore, \n  AgentConfig, \n  Type, \n  GoogleProvider \n} = require('@areumtecnologia/agentic-core');\n\n// 1. Configurar o agente (suporta construtor direto ou encadeamento fluente)\nconst agentConfig = new AgentConfig()\n  .setName('Monnalisa')\n  .setCompany('Áreum Tecnologia', 'Soluções em IA e Automação de Processos.')\n  .setMission('Agente de Vendas', 'Atuar como assistente virtual e agente de vendas.', 'Atenda os clientes cordialmente.')\n  .setReasoningLanguage('pt-BR');\n\n// 2. Instanciar o agente com provedor\nconst agent = new AgenticCore({\n  provider: new GoogleProvider({\n    apiKey: process.env.GOOGLE_GEMINI_API_KEY,\n    model: 'gemma-4-26b-a4b-it'\n  }),\n  debounceMs: 1500,\n  agent: agentConfig,\n});\n\n// 3. Registrar ferramentas\nagent.registerTool({\n  name: 'get_product_info',\n  description: 'Obtém informações de produtos disponíveis.',\n  parameters: {\n    type: Type.OBJECT,\n    properties: {\n      category: { type: Type.STRING, description: 'Categoria do produto.' },\n    },\n  },\n}, async ({ category }, signal) => {\n  return JSON.stringify({ products: ['Produto A', 'Produto B'] });\n});\n\n// 4. Criar sessão (aceita string ou número como ID)\nconst session = agent.createSession('session-001', {\n  name: 'João Silva',\n  phone: '+55 11 98765-4321',\n  email: 'joao@exemplo.com',\n});\n\n// 5. Processar mensagens\nconst response = await agent.processMessage(session.id, 'Olá!');\nconsole.log(response.response);\n```\n\n---\n\n## 🛠️ Ferramentas Nativas Embutidas (v3.3.1)\n\nA versão 3.3.1 adiciona **três ferramentas nativas de primeira classe** que podem ser ativadas diretamente via flags no construtor do `AgenticCore`, sem necessidade de configuração manual ou chaves de API externas:\n\n```javascript\nconst agent = new AgenticCore({\n  agent: agentConfig,\n  provider: new OllamaProvider({ model: 'qwen3:0.6b' }),\n  calculatorTool: true, // Avaliação matemática determinística isolada\n  reasoningTool: true,  // Pensamento sequencial estruturado (scratchpad)\n  webSearchTool: true   // Pesquisa na Web gratuita em tempo real\n});\n```\n\n### 1. 🧮 Cálculo Matemático Determinístico (`calculatorTool`)\n\nModelos de linguagem frequentemente alucinam em operações aritméticas ou cálculos encadeados. Com `calculatorTool: true` (ou `mathTool: true`), o agente recebe a ferramenta `calculate_expression`, delegando cálculos para um motor determinístico seguro baseado em `node:vm`:\n\n- **Sandbox Blindada**: Escopo isolado sem acesso a `process`, `require`, `fs`, `global` ou protótipos de execução (proteção anti-RCE).\n- **Timeout Estrito**: Interrupção forçada em no máximo 1.500ms contra loops infinitos.\n- **Funções Matemáticas Suportadas**: Todas as funções do objeto padrão `Math` (`Math.sqrt`, `Math.pow`, `Math.sin`, `Math.round`, etc.) e operadores padrão (`+`, `-`, `*`, `/`, `%`, `**`).\n\n```javascript\n// O agente chama automaticamente calculate_expression para responder:\nconst res = await agent.processMessage(session.id, 'Quanto é (45 * 12) + (130 / 2) - 15?');\nconsole.log(res.response); // \"O resultado é 590.\"\n```\n\n### 2. 🧩 Raciocínio Sequencial Passo a Passo (`reasoningTool`)\n\nInspirado no paradigma *Sequential Thinking*, a flag `reasoningTool: true` ativa a ferramenta `record_thought_step` (alias `recordThoughtStep`). O agente utiliza um scratchpad dinâmico para estruturar problemas complexos antes de sintetizar a resposta final:\n\n- **Metadados Estruturados**: Cada passo registra `thoughtNumber`, `totalThoughts`, `isRevision`, `revisesThought` e `hypothesis`.\n- **Emissão em Tempo Real**: Cada etapa de pensamento emite o evento `AgentEvents.REASONING_CHUNK` no agente e eventos do tipo `thought` no streaming.\n- **Histórico Consolidado**: O raciocínio acumulado é retornado em `result.reasoning` e salvo no histórico da sessão.\n\n```javascript\nagent.on(AgentEvents.REASONING_CHUNK, ({ thought, thoughtNumber, totalThoughts }) => {\n  console.log(`[Pensamento ${thoughtNumber}/${totalThoughts}]: ${thought}`);\n});\n\nconst res = await agent.processMessage(\n  session.id, \n  'Analise os prós e contras de migrar uma arquitetura monolítica para microsserviços passo a passo.'\n);\n```\n\n### 3. 🌐 Pesquisa na Web Nativa e Gratuita (`webSearchTool`)\n\nCom `webSearchTool: true` (ou `searchTool: true`), o agente ganha a capacidade de consultar a internet em tempo real através da ferramenta `web_search`:\n\n- **100% Gratuita e sem API Keys**: Utiliza o motor de busca do DuckDuckGo HTML com raspagem semântica robusta.\n- **Decodificação de Links**: Resolve automaticamente URLs de redirecionamento interno (`//duckduckgo.com/l/?uddg=...`).\n- **Segurança Anti-SSRF Integrada**: Bloqueia endereços IP privados, localhost e metadados de nuvem.\n\n```javascript\nconst res = await agent.processMessage(\n  session.id, \n  'Pesquise as novidades mais recentes lançadas no Node.js 22 e resuma os principais pontos.'\n);\nconsole.log(res.response);\n```\n\n### ⚡ 100% de Precisão Comprovada com Modelos Compactos (SLMs)\n\nO `AgenticCore` conta com roteamento inteligente de intenção e parser resiliente de chamadas XML/JSON (`<tool_call>...`), garantindo que até mesmo modelos ultracompactos locais rodem ferramentas com 100% de assertividade:\n\n- **Bateria de Testes com `qwen3:0.6b` (Ollama local)**:\n  - 🧮 Cálculo Matemático: **10/10 (100% de sucesso)**\n  - 🧩 Raciocínio Sequencial: **10/10 (100% de sucesso)**\n  - 🌐 Pesquisa na Web: **10/10 (100% de sucesso)**\n  - **Total Geral: 30/30 (100% de aprovação)**\n\n---\n\n## ⚡ Streaming em Tempo Real (v3.3)\n\nO Agentic Core v3.3 introduz suporte nativo a streaming completo de tokens e pensamentos em tempo real através do `TokenStream`:\n\n```javascript\nconst { AgenticCore, AgentConfig, OpenAIProvider } = require('@areumtecnologia/agentic-core');\n\nconst agent = new AgenticCore({\n  agent: new AgentConfig().setName('StreamAgent').setReasoningLanguage('pt-BR'),\n  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' })\n});\n\nconst session = agent.createSession('sess-stream-1', { name: 'Cliente' });\n\n// Inicia streaming em tempo real\nconst stream = agent.processMessageStream(session.id, 'Explique a teoria da relatividade resumidamente.');\n\n// Consumo via iteração assíncrona\nfor await (const chunk of stream) {\n  if (chunk.type === 'token') {\n    process.stdout.write(chunk.text);\n  } else if (chunk.type === 'thought') {\n    console.log(`\\n[Raciocínio interno: ${chunk.thought}]\\n`);\n  } else if (chunk.type === 'tool_call') {\n    console.log(`\\n[Executando ferramenta: ${chunk.toolCall.name}]...\\n`);\n  }\n}\n\n// A resposta final estruturada pode ser obtida ao final\nconst finalResult = await stream.response;\nconsole.log('\\nFinalizado:', finalResult.sent_at);\n```\n\n---\n\n## 🧠 Memória & Auto-RAG (v3.3)\n\nCom `autoRetrieveMemory: true`, o `ContextAugmenter` pesquisa automaticamente memórias semânticas e episódicas antes de cada turno e enriquece a mensagem enviada ao modelo:\n\n```javascript\nconst { AgenticCore, InMemoryStore, AgentConfig, GoogleProvider } = require('@areumtecnologia/agentic-core');\n\nconst store = new InMemoryStore();\nconst core = new AgenticCore({\n  agent: new AgentConfig().setName('SupportAgent'),\n  provider: new GoogleProvider({ apiKey: process.env.GOOGLE_GEMINI_API_KEY }),\n  memoryStore: store,\n  autoRetrieveMemory: true // Ativa RAG automático de memória\n});\n\n// Ensina fatos à memória duradoura do cliente\nawait core.semanticMemory.learn({\n  sessionId: 'sess-001',\n  subject: 'plano_usuario',\n  predicate: 'tipo',\n  object: 'Plano Enterprise VIP'\n});\n\nconst session = core.createSession('sess-001', { name: 'Carlos' });\n\n// O modelo recebe automaticamente o contexto histórico relevante!\nconst response = await core.processMessage(session.id, 'Qual é o meu plano?');\nconsole.log(response.response);\n```\n\n---\n\n## 🛡️ Segurança, Sandboxing e Políticas de Ferramentas (v3.3)\n\n### 1. `ToolSecurityPolicy` (Rate Limiting e Listas de Bloqueio)\n\nControle quais ferramentas podem ser chamadas e com que frequência:\n\n```javascript\nconst { ToolSecurityPolicy, AgenticCore } = require('@areumtecnologia/agentic-core');\n\nconst securityPolicy = new ToolSecurityPolicy({\n  blockedTools: ['execute_command', 'delete_database'],\n  maxInvocationsPerMinute: 20 // Limite de chamadas por minuto por sessão\n});\n\nconst core = new AgenticCore({\n  agent,\n  provider,\n  securityPolicy // Aplicado globalmente em todas as execuções de tools\n});\n```\n\n### 2. Confinamento de Diretório em `FileTools`\n\nEvita ataques de *path traversal* (como `../../etc/passwd`) e bloqueia leitura de arquivos confidenciais (`.env`, `.git`, chaves privadas, certificados):\n\n```javascript\nconst { FileTools } = require('@areumtecnologia/agentic-core');\n\nconst fileTools = new FileTools({\n  baseDir: './workspace/safe_dir' // Apenas caminhos dentro de safe_dir são permitidos\n});\n```\n\n### 3. Proteção Anti-SSRF em `WebTools`\n\nBloqueia chamadas para endereços de rede privada, `localhost` e metadados de nuvem (`169.254.169.254`, `metadata.google.internal`):\n\n```javascript\nconst { WebTools } = require('@areumtecnologia/agentic-core');\n\nconst webTools = new WebTools();\n// URLs privadas ou de metadados disparam SecurityViolation e são bloqueadas automaticamente\n```\n\n---\n\n## 📊 Observabilidade e Telemetria (v3.3)\n\nMonitore spans de execução, duração em milissegundos e consumo acumulado de tokens com o `TelemetryProvider`:\n\n```javascript\nconst { TelemetryProvider, AgenticCore } = require('@areumtecnologia/agentic-core');\n\nconst telemetry = new TelemetryProvider();\n\ntelemetry.on('span:end', (span) => {\n  console.log(`[Trace] Span \"${span.name}\" concluído em ${span.durationMs}ms com status: ${span.status}`);\n});\n\ntelemetry.on('metrics:tokens', ({ added, cumulative }) => {\n  console.log(`[Tokens] +${added.total} tokens (Acumulado: ${cumulative.totalTokens})`);\n});\n\nconst core = new AgenticCore({\n  agent,\n  provider,\n  telemetry // Registra automaticamente spans de mensagens, geração de modelo e execução de ferramentas\n});\n```\n\n---\n\n## 🌐 Orquestração de Tarefas em Grafo (DAG)\n\nOrquestre grafos de tarefas com dependências, condições de branch e transformação dinâmica de dados:\n\n```javascript\nconst { TaskGraph, ParallelExecutor } = require('@areumtecnologia/agentic-core');\n\nconst graph = new TaskGraph();\n\n// Tarefa base\ngraph.add({\n  id: 'analise_credito',\n  fn: async () => ({ score: 850, aprovado: true })\n});\n\n// Tarefa condicional (só executa se aprovado)\ngraph.add({\n  id: 'gerar_contrato',\n  deps: ['analise_credito'],\n  condition: (ctx) => ctx.results.analise_credito.aprovado === true,\n  transformContext: (ctx) => ({ scoreCliente: ctx.results.analise_credito.score }),\n  fn: async (transformedContext) => ({ contratoId: 'CTR-9988', dados: transformedContext })\n});\n\n// Tarefa de rejeição (será ignorada/skipped)\ngraph.add({\n  id: 'notificar_recusa',\n  deps: ['analise_credito'],\n  condition: (ctx) => ctx.results.analise_credito.aprovado === false,\n  fn: async () => ({ emailEnviado: true })\n});\n\nconst executor = new ParallelExecutor(graph);\nconst results = await executor.run();\n\nconsole.log('Contrato gerado:', results.gerar_contrato);\nconsole.log('Recusa:', results.notificar_recusa.status); // 'skipped'\n```\n\n---\n\n## 🤖 SubAgentes com Delegação de Tarefas\n\nO `SubAgent` permite executar tarefas especializadas em segundo plano utilizando a infraestrutura do agente pai:\n\n- Possui **sessão efêmera própria** limpa automaticamente ao finalizar.\n- Suporta **ferramentas temporárias** desregistradas automaticamente no bloco `finally`.\n\n```javascript\nconst { SubAgent, AgentConfig } = require('@areumtecnologia/agentic-core');\n\nconst subConfig = new AgentConfig('Pesquisador', 'Áreum', '...', 'Pesquisador', 'Buscar dados', '...');\n\nconst researcher = new SubAgent({\n  parent: mainAgent,\n  config: subConfig,\n  name: 'researcher-subagent',\n  tools: [/* ferramentas exclusivas do subagente */]\n});\n\nconst result = await researcher.execute('Pesquisar relatório financeiro do setor');\nconsole.log(result.output);\n```\n\n---\n\n## 🏢 Plataforma Multi-Tenant e Persistência\n\n### `PlatformManager`\nGerencie múltiplos tenants com instâncias de agentes e métricas isoladas:\n\n```javascript\nconst { PlatformManager } = require('@areumtecnologia/agentic-core');\n\nconst platform = new PlatformManager();\nplatform.registerTenant('tenant-empresa-a');\nconst tenantAgent = platform.createAgent('tenant-empresa-a', agentConfig, { provider });\n```\n\n### `SessionStore` & `InMemorySessionStore`\nPersista e restaure o estado das sessões:\n\n```javascript\nconst { InMemorySessionStore } = require('@areumtecnologia/agentic-core');\n\nconst store = new InMemorySessionStore();\nawait store.save(session.id, session.toJSON());\n```\n\n---\n\n## 🎯 Eventos do Agente\n\nEscute eventos através de `agent.on(AgentEvents.EVENT_NAME, callback)`:\n\n```javascript\nconst { AgentEvents } = require('@areumtecnologia/agentic-core');\n\nagent\n  .on(AgentEvents.TOKEN, ({ token }) => process.stdout.write(token))\n  .on(AgentEvents.REASONING_CHUNK, ({ thought }) => console.log('Pensando:', thought))\n  .on(AgentEvents.TOOL_STREAM_START, ({ toolCall }) => console.log('Iniciando tool:', toolCall.name))\n  .on(AgentEvents.TOOL_STREAM_END, ({ toolResult }) => console.log('Tool finalizada:', toolResult.name))\n  .on(AgentEvents.SESSION_CREATED, ({ session }) => console.log(`Sessão criada: ${session.id}`))\n  .on(AgentEvents.SESSION_UPDATED, ({ session, reason }) => console.log(`Sessão atualizada: ${session.id} (${reason})`))\n  .on(AgentEvents.SESSION_EXPIRED, ({ session }) => console.log(`Sessão expirada: ${session.id}`))\n  .on(AgentEvents.SESSION_CLEARED, ({ session, reason }) => console.log(`Sessão limpa: ${session.id}`))\n  .on(AgentEvents.TURN_START, ({ depth, session }) => console.log(`Turno ${depth} iniciado`))\n  .on(AgentEvents.RESPONSE, ({ response, reasoning, usageMetadata }) => console.log('Resposta:', response))\n  .on(AgentEvents.TOOL_CALL, ({ name, args }) => console.log(`Tool chamada: ${name}`, args))\n  .on(AgentEvents.TOOL_RESULT, ({ name, result }) => console.log(`Tool resultado: ${name}`, result))\n  .on(AgentEvents.PROVIDER_FALLBACK, ({ failedProvider, nextProvider, error }) => console.warn(`Fallback: ${failedProvider} -> ${nextProvider}`))\n  .on(AgentEvents.ERROR, ({ error, source }) => console.error(`Erro [${source}]:`, error.message));\n```\n\n---\n\n## 🔌 Suporte ao Protocolo MCP (Model Context Protocol)\n\nO `McpManager` e o `McpServer` oferecem suporte nativo ao protocolo MCP (JSON-RPC 2.0 via Stdio):\n\n```javascript\n// MCP Client (Importando ferramentas externas)\nconst { McpManager } = require('@areumtecnologia/agentic-core');\nconst mcp = new McpManager(agent);\nawait mcp.registerServer('db', { command: 'node', args: ['mcp-server.js'] });\n\n// MCP Server (Expondo o agente como servidor MCP)\nconst { McpServer } = require('@areumtecnologia/agentic-core');\nconst server = new McpServer(agent);\nserver.start();\n```\n\n---\n\n## 📁 Estrutura do Projeto\n\n```\nagentic-core/\n├── src/\n│   ├── index.js                          # Entry point com exportações completas\n│   ├── AgenticCore.js                    # Core do agente e agentic loop\n│   ├── AgentConfig.js                    # Builder de configuração do agente\n│   ├── AgentSession.js                   # Estado e histórico da sessão\n│   ├── AgentEvents.js                    # Fonte única de verdade de eventos\n│   ├── AgentManager.js                   # Gerenciador de múltiplos agentes\n│   ├── SubAgent.js                       # Agente especializado efêmero\n│   ├── types.js                          # Tipos neutros (Type, ThinkingLevel)\n│   ├── utils.js                          # withRetry com backoff e jitter\n│   ├── streaming/                        # Streaming em tempo real (TokenStream)\n│   ├── telemetry/                        # Observabilidade e tracing (TelemetryProvider)\n│   ├── tools/                            # Sistema de ferramentas embutidas\n│   │   ├── index.js                      # Exportações do sistema de ferramentas\n│   │   ├── ToolRegistry.js               # Registro e descoberta unificada de ferramentas\n│   │   ├── ToolComposer.js               # Composição e chaining de ferramentas\n│   │   ├── ToolValidator.js              # Validação de schema e segurança\n│   │   ├── ToolMarketplace.js            # Marketplace e descoberta\n│   │   ├── ToolSecurityPolicy.js         # Políticas de segurança e rate limiting\n│   │   └── categories/                   # Categorias de ferramentas\n│   │       ├── reasoning.js              # Sequential thinking (record_thought_step)\n│   │       ├── web.js                    # Ferramentas web com busca DuckDuckGo e anti-SSRF\n│   │       ├── file.js                   # Ferramentas de arquivo com path confinement\n│   │       ├── database.js               # Ferramentas de banco de dados\n│   │       ├── system.js                 # Ferramentas de sistema (com sanitização e vm sandbox)\n│   │       └── communication.js          # Ferramentas de comunicação\n│   ├── mcp/                              # Protocolo MCP (Client, Server, Manager)\n│   ├── memory/                           # Memória (Working, Compactor, Episodic, Semantic, ContextAugmenter)\n│   ├── orchestrator/                     # Orquestração (TaskGraph, TaskNode, ParallelExecutor, Orchestrator)\n│   ├── persistence/                      # Persistência (SessionStore, InMemorySessionStore)\n│   ├── platform/                         # Multi-tenancy (PlatformManager)\n│   └── providers/                        # Providers (Google, OpenAI, Anthropic, Ollama, Nvidia)\n├── tests/\n│   ├── test_ten_each.js                  # Bateria de 30 testes de ferramentas nativas (100% de aprovação)\n│   ├── test_evolution_v33.js             # Suíte completa de testes da v3.3.0 (Streaming, RAG, Segurança, DAG, Telemetria)\n│   ├── test_code_review_fixes.js         # Validação de correções da revisão de código\n│   ├── test_v32_improvements.js          # Validação das melhorias da v3.2.0\n│   ├── test_bugs_fix.js                  # Suíte de teste para correções de bugs\n│   ├── test_retry_classification.js      # Validação de erros retentáveis vs permanentes\n│   └── ...                               # Outros testes de serviço e integração\n├── package.json\n└── README.md\n```\n\n---\n\n## 🧪 Testes\n\n```bash\n# Executar suíte padrão completa\nnpm test\n\n# Executar bateria de 30 testes das ferramentas nativas v3.3.1\nnode tests/test_ten_each.js\n\n# Executar suíte de novidades da versão 3.3.0\nnpm run test:evolution\n\n# Executar testes específicos de regressão e correções\nnode tests/test_code_review_fixes.js\nnode tests/test_v32_improvements.js\nnode tests/test_bugs_fix.js\nnode tests/test_retrocompatibility.js\nnode tests/test_retry_classification.js\n```\n\n---\n\n## 📄 Licença\n\nISC\n\n## 👤 Autor\n\n**Áreum Tecnologia** — Software and AI Development Team\n","readmeFilename":"README.md"}