npm package: @muthurasu/vibe-agents
Description: Premium multi-agent orchestration for Node.js via OpenRouter
Author: Vibe-Agents Contributors
Latest version: 1.0.0

# Vibe-Agents 🚀✨

**Vibe-Agents** is a premium Node.js SDK for orchestrating autonomous AI agents with style. A ground-up implementation designed for the JavaScript ecosystem, powered by **OpenRouter** and **Firebase**.

Build complex, multi-agent workflows (Research, Strategy, Writing, Coding) with ease.

---

## 🌟 Key Features

- **🧠 OpenRouter Integration**: One API to rule them all. Use Qwen, GPT-4, Claude 3.5, Llama 3, and any other model available on OpenRouter.
- **💾 Long-term Memory**: Built-in support for **Firebase Firestore** to persist agent states, memory, and task history.
- **🤝 Human Verification (HITL)**: Pause execution for critical decisions. Request human approval via Firebase Realtime Database.
- **⚡ Pro Orchestration**: Choose between `SEQUENTIAL` (step-by-step handover) or `PARALLEL` execution processes.
- **🛡️ Type-Safe**: Fully written in TypeScript for a robust developer experience.

---

## 🚀 Quick Start

### 1. Installation

```bash
npm install @muthurasu/vibe-agents
```

### 2. Configure Environment

Create a `.env` file in your root directory:

```env
OPENROUTER_API_KEY=your_openrouter_api_key_here
```

### 3. Build Your First Agent Squad

```typescript
import { Agent, Squad, ProcessType } from '@muthurasu/vibe-agents';

// 1. Define your specialized agents
const researcher = new Agent({
    name: "Vibe Hunter",
    role: "Trend Researcher",
    goal: "Identify the next big thing in AI agents for 2026",
    backstory: "A sharp, data-driven analyst with a knack for spotting patterns."
});

const writer = new Agent({
    name: "Storyteller",
    role: "Tech Blogger",
    goal: "Create a compelling blog post from research trends",
    backstory: "A creative writer who translates data into engaging narratives."
});

// 2. Define the tasks
const tasks = [
    {
        id: "task-research",
        description: "List 5 emerging trends in AI Agentic Workflows for 2026",
        expectedOutput: "A list of 5 trends with brief descriptions",
        agent: researcher
    },
    {
        id: "task-write",
        description: "Write a 3-paragraph blog post about the identified trends",
        expectedOutput: "A professional blog post in Markdown format",
        agent: writer
    }
];

// 3. Assemble the Squad
const squad = new Squad({
    agents: [researcher, writer],
    tasks: tasks,
    process: ProcessType.SEQUENTIAL // Task 2 will wait for Task 1's output
});

// 4. Kickoff!
async function run() {
    const finalReport = await squad.kickoff();
    console.log("Final Output:\n", finalReport);
}

run();
```

---

## 🛠️ Advanced Usage

### 💾 Enabling Firebase Memory
Vibe-Agents can use Firebase to store task results and context, allowing agents to "remember" past work.

```typescript
import * as admin from 'firebase-admin';
import { Squad } from 'vibe-agents';

// Initialize Firebase Admin SDK first
admin.initializeApp({
    credential: admin.credential.cert(yourSecretsPath)
});

const squad = new Squad({
    agents: [...],
    tasks: [...],
}, true); // Set second param to true to enable Firebase
```

### 🤝 Human Verification (HITL)
For critical tasks, you can require human approval before an agent proceeds. This is handled via Firebase Realtime Database.

```typescript
const task = {
    id: "critical-deploy",
    description: "Prepare deployment configuration",
    expectedOutput: "Config file content",
    agent: sysAdmin,
    requiresApproval: true 
};
```

---

## ⚖️ API Reference

### `Agent`
The core component representing an AI entity.
- `name`: Identifiable name.
- `role`: The job description.
- `goal`: What the agent wants to achieve.
- `backstory`: Context and personality.
- `model`: (Optional) Specific OpenRouter model (default: `qwen/qwen3-vl-235b-a22b-thinking`).

### `Task`
A specific mission for an agent.
- `id`: Unique identifier.
- `description`: Detailed instructions.
- `expectedOutput`: What the result should look like.
- `agent`: The agent assigned to this task.

### `Squad`
The orchestrator that manages agents and execution.
- `agents`: List of agents.
- `tasks`: List of tasks to be performed.
- `process`: `ProcessType.SEQUENTIAL` or `ProcessType.PARALLEL`.

---

## 📜 Disclaimer

**Vibe-Agents** is an independent project. While inspired by autonomous agent concepts, this is a separate implementation built from scratch for Node.js.

## ⚖️ License

Distributed under the **MIT License**. See `LICENSE` for more information.

---
Built with ✨ for the next generation of AI developers.