OverAI TypeScript Node.js AI Agents Framework


!OverAI Logo

OverAI is the comprehensive, production-ready AI Agents framework designed for Builders, Entrepreneurs, and Enterprise Developers.

Unlike other frameworks that stop at "Hello World", OverAI provides the full stack needed to Build, Deploy, and Monetize AI solutions. From simple automation scripts to full-fledged AI SaaS platforms with billing, API keys, and workflow integrations.

📣 Join the Community

Follow this link to join the WhatsApp group: Join the WhatsApp Community

🚀 Why Choose OverAI?

$3

* Business-in-a-Box: Launch your AI API in minutes with built-in Stripe simulation, Credit/Quota management, and API Key authentication.
* Monetization Ready: Every agent interaction can be tracked and billed.
* White-Label Friendly: Designed to be the backend of your product.

$3

* Type-Safe & Scalable: Built entirely in TypeScript for robust, maintainable code.
* Multi-Agent Orchestration: Create teams of agents that collaborate, delegate, and solve complex problems.
* Protocol Agnostic: Native support for MCP (Model Context Protocol) to connect with any data source.
* Workflow Integration: Seamlessly trigger agents from N8N, Zapier, or your own webhooks.

🆚 OverAI vs Low-Code (n8n, Zapier)

While tools like n8n and Zapier are excellent for linear automation (e.g., "If email received -> add row to Sheet"), OverAI is designed for Autonomous Reasoning and Software Engineering.

| Feature | 🧩 n8n / Zapier (Low-Code) | 🧠 OverAI (Code-First) |
| :--- | :--- | :--- |
| Best For | Linear Workflows ("If This Then That") | Complex Reasoning (Loops, Self-correction, Dynamic Decisions) |
| Control | Limited by visual nodes | Unlimited (Full TypeScript/Python power) |
| Maintenance | Visual Interface (Hard to version control) | Git-Based (Pull Requests, History, Diff) |
| Quality Assurance | Hard to test automatically | Unit Tests & CI/CD (Jest, GitHub Actions) |
| Monetization | Difficult to hide logic / resell | Easy to Package (Compile to Binary/API, protect IP) |
| Performance | Overhead of visual platform | High Performance (Serverless ready, 0ms cold start optimized) |

When to use which?
Use n8n for plumbing: Connecting Webhook A to Database B.*
Use OverAI for the brain: Analyzing data, making decisions, generating intelligent content, and building SaaS products.*

---

📦 Installation

``bash
npm install overai
`

✨ Auto-Coder CLI (Magic Project Generator)

Want to build a project instantly? OverAI includes a powerful CLI that can scaffold entire projects (React, Node, Python, etc.) from a single prompt.

Usage:

`bash


1. Set your API Key (OpenAI, Gemini, or Anthropic)

export OPENAI_API_KEY=sk-...

OR

export GOOGLE_API_KEY=AIza...

2. Run the magic command

npx overai-create "A personal portfolio website with HTML/CSS"
`

Options:

* Auto-Detection: The CLI automatically picks the best model based on your environment variables.
* Force Model: You can specify a model manually:
`bash
npx overai-create "A snake game in Python" --model google/gemini-2.0-flash-exp
`

---

⚡ Quick Start: Gemini Example

1. Create tsconfig.json:
`json
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "node",
"target": "ES2020",
"esModuleInterop": true,
"skipLibCheck": true,
"strict": true,
"resolveJsonModule": true,
"allowSyntheticDefaultImports": true
},
"ts-node": {
"esm": true,
"experimentalSpecifierResolution": "node"
}
}
`

2. Create main.ts:
`typescript
import { Agent, OverAI } from 'overai';

async function main() {
// 1. Créer un agent
const agent = new Agent({
name: "GeminiAgent",
instructions: "Tu es Gemini, un modèle de Google. Réponds en français.",
llm: "google/gemini-2.0-flash",
verbose: true
});

// 2. Configurer OverAI avec l'agent et une tâche
const overAI = new OverAI({
agents: [agent],
tasks: ["Explique-moi ce qu'est un Agent IA en une phrase simple."],
verbose: true
});

// 3. Lancer l'exécution
console.log("🚀 Démarrage de OverAI...");
try {
const result = await overAI.start();
console.log("\n✅ Résultat :");
console.log(result);
} catch (error) {
console.error("❌ Erreur :", error);
}
}

main();
`

3. Run the agent:
`bash
export GOOGLE_API_KEY="your-gemini-key"
npx tsx main.ts
`

---

🤝 Multi-Agent Collaboration

Create a team of agents that work together.

`typescript
import { Agent, OverAI } from 'overai';

async function main() {
const researcher = new Agent({
name: "Researcher",
instructions: "Research the latest trends in AI.",
});

const writer = new Agent({
name: "Writer",
instructions: "Write a blog post based on the research provided.",
});

const overAI = new OverAI({
agents: [researcher, writer],
tasks: [
"Research 3 top AI trends for 2025.",
"Write a short blog post summarizing these trends."
],
verbose: true
});

await overAI.start();
}
main();
`

---

🧩 Multi-Agent System Examples

$3

`typescript
import { Agent, Agents } from 'overai';

async function main() {
const researcher = new Agent({
name: 'Researcher',
role: 'Research Specialist',
goal: 'Find accurate information on topics',
instructions: 'You research topics thoroughly and provide factual information.',
llm: 'openai/gpt-4o-mini'
});

const writer = new Agent({
name: 'Writer',
role: 'Content Writer',
goal: 'Create engaging content from research',
instructions: 'You write clear, engaging content based on the research.',
llm: 'openai/gpt-4o-mini'
});

const system = new Agents({
agents: [researcher, writer],
tasks: [
{ agent: researcher, description: 'Research: Benefits of TypeScript' },
{ agent: writer, description: 'Write a 200-word article about these benefits' }
],
process: 'sequential'
});

const result = await system.start();
console.log('Final result:', result);
}

main().catch(console.error);
`

$3

`typescript
import { Agent, Agents, createMCP } from 'overai';

async function main() {
const mcp = await createMCP({
transport: {
type: 'stdio',
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '.']
}
});

const tools = await mcp.tools();
const mcpTools = Object.values(tools);

const fileOps = new Agent({
name: 'FileOps',
instructions: 'List TypeScript files in the current directory.',
tools: mcpTools,
llm: 'openai/gpt-4o-mini'
});

const writer = new Agent({
name: 'Writer',
instructions: 'Write a brief summary of the detected files.',
llm: 'openai/gpt-4o-mini'
});

const system = new Agents({
agents: [fileOps, writer],
tasks: [
{ agent: fileOps, description: 'List TypeScript files' },
{ agent: writer, description: 'Summarize the results' }
],
process: 'sequential'
});

const result = await system.start();
console.log('Final result:', result);

await mcp.close();
}

main().catch(console.error);
`

---

💸 SaaS & Monetization Starter Kit

OverAI comes with a complete SaaS API Server example. Use this to launch your own AI business.

$3


- Authentication: Secure API Key middleware (x-api-key).
- Billing System: Credit deduction per request (1 credit = 1 request).
- Payment Gateway: Mock Stripe integration to simulate top-ups.
- Webhooks: N8N compatible endpoints.

$3

1. Set your OpenAI Key:
`bash
export OPENAI_API_KEY="sk-..."
`

2. Start the Server:
`bash
npx ts-node examples/saas-server.ts
`
Server starts at http://localhost:3001

3. Test Monetization:
* Top-up Credits (Simulate Stripe):
`bash
curl -X POST http://localhost:3001/api/billing/topup \
-H "Content-Type: application/json" \
-H "x-api-key: sk_demo_12345" \
-d '{"amount": 10.00}'
`
* Paid Chat Request:
`bash
curl -X POST http://localhost:3001/api/v1/agent/chat \
-H "Content-Type: application/json" \
-H "x-api-key: sk_demo_12345" \
-d '{"message": "Hello, I paid for this!"}'
`

---

🔌 Integrations & Workflows

$3

OverAI agents can be triggered via webhooks, making them perfect for N8N workflows.

`typescript
// Example N8N Webhook Endpoint (included in saas-server.ts)
app.post('/api/webhook/n8n', async (req, res) => {
const { workflow_data } = req.body;
// Process N8N data with agents...
res.json({ status: "success", result: agentResponse });
});
`

$3

Support for the MCP standard allows your agents to safely access local files, databases, and external tools without custom glue code.

---

🤝 A2A (Agent‑to‑Agent) Optionnel

OverAI fournit une couche A2A optionnelle pour la négociation et la coordination entre agents, activable à la demande et sans modifier vos agents existants.

- Activer la couche A2A par variable d’environnement:
`bash
export OVERAI_A2A_ENABLED=true
`
- Imports publics:
`typescript
import { Agent, Router } from 'overai';
import { ChannelManager, OverAIAdapter } from 'overai/a2a';
`
- Exemple minimal:
`typescript
const cm = new ChannelManager(); // activé si OVERAI_A2A_ENABLED=true
const writer = new Agent({ instructions: 'Tu rédiges des fiches produit' });
const seo = new Agent({ instructions: 'Tu optimises SEO' });

const router = new Router({
writer: { agent: writer, keywords: ['rédige', 'fiche'] },
seo: { agent: seo, keywords: ['seo', 'métadonnées', 'balises'] }
}, { default: 'writer' });

const a2a = new OverAIAdapter({
channel: cm,
agents: { writer, seo },
router
});

cm.openChannel('ch-1', ['writer', 'seo']);
await a2a.handle({
type: 'propose',
channelId: 'ch-1',
from: 'writer',
to: 'seo',
timestamp: Date.now(),
taskId: 'task-123',
proposal: {
goal: 'Optimiser la fiche produit pour SEO',
steps: ['mots-clés', 'meta', 'FAQ', 'JSON-LD']
}
});
`

Cette couche est facultative et isolée: si OVERAI_A2A_ENABLED n’est pas défini à true, le module reste inactif et vos agents fonctionnent comme d’habitude.

---

🤖 OpenClaw Integration (IoT & Automation)

OverAI natively integrates with OpenClaw, a local gateway that allows your agents to control physical devices, desktop applications, and messaging platforms (WhatsApp, Discord, Telegram, etc.).

$3

1. Install OpenClaw CLI:
`bash
npm install -g openclaw
`

2. Start the Local Gateway:
Run this command in a separate terminal to start the OpenClaw server (default port: 18789):
`bash
openclaw gateway
`

$3

Simply import the openclawSend tool and add it to your agent. The agent can then use natural language to interact with any device or service connected to your OpenClaw Gateway.

`typescript
import { Agent, OverAI } from 'overai';
import { openclawSend } from 'overai';

async function main() {
// 1. Create an agent with the OpenClaw tool
const homeAssistant = new Agent({
name: "HomeAssistant",
instructions: "You are a helpful home automation assistant. You can control devices and send messages via OpenClaw.",
tools: [openclawSend()], // Add the tool here
llm: "openai/gpt-4o"
});

// 2. Give it a command that requires real-world interaction
const overAI = new OverAI({
agents: [homeAssistant],
tasks: [
"Send a WhatsApp message to Mom saying 'I'll be late for dinner'",
"Turn off the living room lights"
]
});

await overAI.start();
}

main();
`

Note: The agent will automatically detect that it needs to use openclawSend to fulfill these requests and will format the commands appropriately for the OpenClaw Gateway.

---

🧠 Native RAG (Knowledge Base)

Give your agents a long-term memory or specialized knowledge base in 3 lines of code.

`typescript
import { Agent, KnowledgeBase, createKnowledgeTool } from 'overai';

// 1. Create and populate Knowledge Base
const kb = new KnowledgeBase();
await kb.addText("The secret code is 42.");
await kb.addText("Project X launch date is October 15th.");

// 2. Add the search tool to your agent
const agent = new Agent({
instructions: "You are a helpful assistant.",
tools: [createKnowledgeTool(kb)]
});

// 3. Ask questions
await agent.start("What is the launch date for Project X?");
`

---

✋ Human-in-the-Loop

For sensitive operations, force the agent to ask for permission or clarification.

`typescript
import { Agent, askHuman } from 'overai';

const agent = new Agent({
instructions: "You are a payment assistant.",
tools: [askHuman()] // Add the human interaction tool
});

await agent.start("Send $500 to Alice, but ask me for confirmation first.");
// Agent will output: "Do you confirm sending $500 to Alice?"
// And wait for your input in the terminal.
`

---

🛠️ Development

To contribute or modify the framework:

1. Clone your fork:
`bash
git clone https://github.com/your-username/overai.git
cd overai
`

2. Install & Build:
`bash
npm install
npm run build
`

💰 Business-in-a-Box (SaaS Starter Kit)

Launch your own AI API business in minutes. We provide a complete SaaS Server Example including:
* Stripe Integration (Mock): Simulate payments and top-ups.
* Credit System: Deduct credits per request (1 credit = 1 request).
* API Authentication: Secure endpoints with API Keys.
* Rate Limiting: Prevent abuse from free users.

Run the SaaS Server:
`bash


Install dependencies

npm install express @types/express

Run the server

npx ts-node examples/saas-server.ts
`

Test your API:
`bash
curl -X POST http://localhost:3001/api/v1/agent/chat \
-H "Content-Type: application/json" \
-H "x-api-key: sk_demo_12345" \
-d '{"message": "Hello, explain how you work in 1 sentence."}'
`

🏢 Enterprise & Licensing (Open Core)

OverAI follows an Open Core model. The core framework is MIT-licensed and free forever.
For enterprises requiring advanced features, we provide a commercial license that unlocks:

* SSO & Identity: Integrate with Okta, Active Directory, and Google Workspace.
* Audit Logs: Comprehensive tracking of every agent action for compliance.
* Role-Based Access Control (RBAC): Fine-grained permissions for teams.
* Priority Support: SLA-backed support with < 4h response time.

To enable enterprise features:

`typescript
import { license } from 'overai';

// Verify your license key
await license.setLicenseKey(process.env.OVERAI_LICENSE_KEY);

if (license.hasFeature('audit_logs')) {
console.log("✅ Enterprise Audit Logs Enabled");
}
``

Contact sales@overai.com for pricing and details.

License

MIT

Author

JMK
* Email: anouslecode@gmail.com