OverAI TypeScript Node.js AI Agents Framework

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?

💼 For Entrepreneurs & SaaS Builders

• 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.

👨‍💻 For Developers & Engineers

• 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

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:

# 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:

  npx overai-create "A snake game in Python" --model google/gemini-2.0-flash-exp

⚡ Quick Start: Gemini Example

1. Create tsconfig.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:

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:

export GOOGLE_API_KEY="your-gemini-key"
npx tsx main.ts

🤝 Multi-Agent Collaboration

Create a team of agents that work together.

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

Example 1 — Two agents running sequentially

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);

Example 2 — Multi-agent with MCP tools (filesystem via npx)

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.

Features Included:

• 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.

How to Run Your SaaS Backend:

1. Set your OpenAI Key:

   export OPENAI_API_KEY="sk-..."

2. Start the Server:

   npx ts-node examples/saas-server.ts

   Server starts at http://localhost:3001

3. Test Monetization:

   • Top-up Credits (Simulate Stripe):

     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:

     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

N8N Integration

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

// 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 });
});

Model Context Protocol (MCP)

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

🛠️ Development

To contribute or modify the framework:

1. Clone your fork:

   git clone https://github.com/your-username/overai.git
   cd overai

2. Install & Build:

   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:

# Install dependencies
npm install express @types/express

# Run the server
npx ts-node examples/saas-server.ts

Test your API:

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:

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 [email protected] for pricing and details.

License

MIT

Author

JMK

• Email: [email protected]