AI-Autonomous-Agent

A fully autonomous AI agent framework in Node.js/TypeScript with modular plugin system, memory management, and LLM integration.

Features

• Agent Management: Create, run, pause, resume, and delete AI agents
• Goal Decomposition: Automatic task planning using LLM
• Plugin System: Extensible skill plugins for web scraping, file operations, API calls, notifications
• Memory Management: Short-term (in-memory) and long-term (PostgreSQL) memory with vector store support
• LLM Integration: Support for OpenAI GPT and Anthropic Claude models
• Scheduling: Cron-based task scheduling and event queue
• Human-in-the-Loop: Approval workflow for sensitive tasks
• CLI & Programmatic API: Full command-line interface and TypeScript API

Installation

npm install ai-autonomous-agent

Quick Start

CLI Usage

# Create an agent with a goal
npx ai-agent create "Research competitor products" --name ResearchBot

# Run an agent
npx ai-agent run <agentId>

# List all agents
npx ai-agent list

# Check agent status
npx ai-agent status <agentId>

# Pause/Resume agents
npx ai-agent pause <agentId>
npx ai-agent resume <agentId>

# View available plugins
npx ai-agent plugin list

Programmatic Usage

import { AgentManager, getAgentManager, createAgent, runAgent } from 'ai-autonomous-agent';

// Quick start - create and run
await runAgent({
  name: 'ResearchBot',
  goals: ['Research competitor products', 'Compile findings into report'],
  plugins: ['webScraper', 'fileHandler'],
  llmProvider: 'openai',
  onTaskComplete: (taskId, result) => {
    console.log(`Task ${taskId} completed:`, result);
  }
});

// Or with more control
const manager = getAgentManager();

const agent = await manager.create({
  name: 'MyAgent',
  goals: ['Analyze market trends'],
  plugins: ['webScraper', 'apiCaller'],
  llmProvider: 'claude',
  maxConcurrentTasks: 3,
  requireApproval: false
});

// Subscribe to events
agent.on('task:started', (event) => console.log('Started:', event));
agent.on('task:completed', (event) => console.log('Completed:', event));
agent.on('task:failed', (event) => console.log('Failed:', event));

// Run the agent
await agent.run();

Environment Variables

# Required for LLM integration
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Optional for long-term memory
DATABASE_URL=postgres://user:pass@localhost:5432/agents

# Optional
LOG_LEVEL=info  # debug, info, warn, error

Plugins

Built-in Plugins

• webScraper: Web scraping and browser automation (Puppeteer)
• fileHandler: File system operations (read, write, list, delete)
• apiCaller: HTTP API calls (GET, POST, PUT, DELETE)
• notifier: Notifications (email, Slack, webhooks)

Using Plugins

const agent = await manager.create({
  name: 'ScraperBot',
  goals: ['Scrape product prices from competitor websites'],
  plugins: ['webScraper', 'fileHandler']
});

Creating Custom Plugins

import { BasePlugin, Task, AgentContext, TaskResult } from 'ai-autonomous-agent';

class MyCustomPlugin extends BasePlugin {
  name = 'myPlugin';
  description = 'Does something awesome';
  version = '1.0.0';
  keywords = ['custom', 'awesome'];

  async execute(task: Task, context: AgentContext): Promise<TaskResult> {
    const startTime = Date.now();

    try {
      // Your plugin logic here
      const result = await doSomethingAwesome(task, context);

      return this.success(result, Date.now() - startTime);
    } catch (error) {
      return this.failure(error.message, Date.now() - startTime);
    }
  }
}

Memory System

Short-term Memory

Automatically managed in-memory storage with TTL support.

// Accessing via context in plugins
await context.memory.set('key', value, ttl);
const data = await context.memory.get('key');

Long-term Memory (PostgreSQL)

Configure DATABASE_URL environment variable for persistent storage.

Vector Store

Semantic search capability for context-aware retrieval.

import { MemoryManager } from 'ai-autonomous-agent';

const memory = new MemoryManager(agentId, {
  enableVectorStore: true
});

await memory.storeWithEmbedding('doc1', content, 'text for embedding');
const results = await memory.search('similar text query');

Scheduling

import { Scheduler } from 'ai-autonomous-agent';

const scheduler = new Scheduler();

// Schedule recurring task (cron format)
scheduler.schedule(agentId, taskId, '0 9 * * *'); // Every day at 9am

// Schedule one-time task
scheduler.scheduleOnce(agentId, taskId, new Date('2024-12-01T10:00:00'));

Human-in-the-Loop

import { ApprovalManager } from 'ai-autonomous-agent';

const approvals = new ApprovalManager({
  webhookUrl: 'https://your-app.com/webhook'
});

// Listen for approval requests
approvals.on('approval:requested', async (request) => {
  console.log('Approval needed:', request);
  // Notify human via Slack, email, etc.
});

// Approve or reject
approvals.approve(requestId, '[email protected]', 'Looks good');
approvals.reject(requestId, '[email protected]', 'Not safe');

Architecture

User CLI/API
    │
Agent Manager (create/run/pause/delete agents)
    │
Agent Core (Task Planner, Memory Manager, Context Manager, LLM Executor)
    │
Skill Plugin Engine (Web scraping, API calls, file ops)
    │
Scheduler/Event Queue (Cron, recurring, dependency)
    │
Human-in-Loop (Webhook/dashboard approvals)

API Reference

AgentManager

const manager = getAgentManager();

// Create agent
const agent = await manager.create(config);

// Get agent
const agent = manager.get(agentId);

// List agents
const agents = manager.list();
const running = manager.listByStatus('running');

// Lifecycle
await manager.run(agentId);
await manager.pause(agentId);
await manager.resume(agentId);
await manager.stop(agentId);
await manager.delete(agentId);

// Status
const status = manager.status(agentId);
const summary = manager.getSummary();

Agent

// Events
agent.on('agent:started', handler);
agent.on('agent:completed', handler);
agent.on('task:started', handler);
agent.on('task:completed', handler);
agent.on('task:failed', handler);
agent.on('task:approval_required', handler);

// Methods
await agent.run();
await agent.pause();
await agent.resume();
await agent.stop();
await agent.addGoal('New goal');
const status = agent.getStatus();

License

MIT