Overview

n-agents is a minimal yet powerful framework for building AI-powered agents in Node.js. Each agent is a self-contained specialist that uses LLM reasoning (via Ollama) to autonomously execute multi-step tasks by calling tools — no chat required.

• 🧩 Composable — Mix and match pre-built tools to create custom agents
• 🔧 Tool-driven — Agents act by calling typed tool functions, not by chatting
• 🛡️ Stealth browser — Built-in Puppeteer agent with anti-detection and human-like behavior
• ☁️ Cloud or local — Connect to Ollama Cloud or run models locally
• 📦 Zero boilerplate — 146 ready-to-use agents for GitHub, Slack, Jira, Gmail, and more
• 🔄 Auto-recovery — Agents retry on tool failures and self-correct hallucinations

Examples

Real-world tasks executed autonomously by n-agents.

Code Snippet

Input

Output

const result = await agent.execute({
  instructions: [
    "Grayscale then resize to 200x200 the image ./apples.jpg",
    "Save the result to ./examples/image/output/apples-processed.jpg",
  ],
});

const result = await agent.execute({
  instructions: [
    "Transform the UI image at ./examples/image-to-html/ui-mockup.png into a self-contained HTML page with embedded CSS",
    "Save the generated HTML file to ./examples/image-to-html/output/generated-ui.html",
  ],
});

generated-ui.html

const result = await agent.execute({
  instructions: [
    "Transform the UI image at ./examples/image-to-react/ui-mockup.png into a React TypeScript component",
    "Save the generated TSX code to ./examples/image-to-react/output/generated-ui.tsx",
  ],
});

generated-ui.tsx

const result = await agent.execute({
  instructions: [
    "Go to https://duckduckgo.com/?q=weather&ia=web",
    "Take a screenshot of the element '[data-layout=\"forecast\"]'",
    "Save it to ./examples/browser-weather/output/weather.png",
  ],
});

duckduckgo.com/weather

const researchResult = await researcher.execute({
  instructions: [
    'Research topic "the impact of AI agents on software engineering" using public web sources',
  ],
});

const writeResult = await writer.execute({
  instructions: [
    "Write a polished Markdown article based on the research brief and save to ./examples/researcher-writer/output/the_impact_of_ai_agents_on_software_engineering.md",
  ],
});

"the impact of AI agents on software engineering"

the_impact_of_ai_agents_on_software_engineering.md

const researchResult = await httpAgent.execute({
  instructions: [
    "Fetch Wikipedia info for 5 landmark space exploration missions",
  ],
});

const reportResult = await reportWriterAgent.execute({
  instructions: [
    "Generate a clean Markdown report with embedded images and save to ./examples/multi-agent/output/report.md",
  ],
});

5 space missions: Apollo_11, Voyager_1, JWST, Curiosity, Artemis_1

report.md

Available Agents

The library ships with 146 pre-configured agents across 19 categories. Each agent is created via a factory function and can be customized with partial overrides.

Agent

Description

Env Vars

GitHub

Repositories, branches, PRs, issues, and releases via the GitHub API.

GITHUB_TOKEN

GitLab

Projects, branches, merge requests, issues, and releases via the GitLab API.

GITLAB_TOKEN GITLAB_HOST

Bitbucket

Repositories, branches, PRs, issues, and pipelines via the Bitbucket API.

BITBUCKET_TOKEN

Git

Branches, commits, diffs, and file operations in the local repository.

—

Linear

Modern software development issue tracking.

LINEAR_API_KEY

Docker

Container management and orchestration.

DOCKER_HOST

Agent

Description

Env Vars

PagerDuty

Incident response and on-call management.

PAGERDUTY_API_KEY PAGERDUTY_FROM_EMAIL

Datadog

Cloud monitoring and analytics.

DATADOG_API_KEY DATADOG_APP_KEY

Sentry

Error tracking and performance monitoring.

SENTRY_AUTH_TOKEN

AWS CloudWatch

Cloud resources monitoring.

AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION

Agent

Description

Env Vars

Slack

Channels, messages, files, reactions, stars, users, and user groups.

SLACK_TOKEN

Discord

Bot integration for reading, managing, and sending messages.

DISCORD_TOKEN

Microsoft Teams

Teams, channels, and messages via Microsoft Graph API.

MICROSOFT_TEAMS_TOKEN

Telegram

Get updates and send messages via the Telegram Bot API.

TELEGRAM_TOKEN

WhatsApp

Send messages and fetch templates via the WhatsApp Business API.

WHATSAPP_TOKEN WHATSAPP_PHONE_NUMBER_ID

Twilio

Send SMS messages and make voice calls.

TWILIO_ACCOUNT_SID TWILIO_AUTH_TOKEN TWILIO_PHONE_NUMBER

Webex

Send messages and create meetings via the Webex API.

WEBEX_TOKEN

Mattermost

Send messages and get channel details.

MATTERMOST_URL MATTERMOST_TOKEN

Agent

Description

Env Vars

Zoom

Create and manage meetings via the Zoom API.

ZOOM_TOKEN

Google Meet

Create and list meetings via the Google Calendar API.

GOOGLE_MEET_TOKEN

Agent

Description

Env Vars

Gmail

Drafts, labels, messages, and threads via the Gmail API.

GMAIL_ACCESS_TOKEN

Outlook

Office 365 email management.

OUTLOOK_API_KEY

Mailchimp

Manage audiences and campaigns.

MAILCHIMP_API_KEY

SendGrid

Transactional email delivery.

SENDGRID_API_KEY

ActiveCampaign

Email automation and CRM.

ACTIVECAMPAIGN_BASE_URL ACTIVECAMPAIGN_API_KEY

Klaviyo

Ecommerce marketing automation.

KLAVIYO_API_KEY

Brevo (Sendinblue)

Email and SMS marketing.

BREVO_API_KEY

Mailgun

Email API integration.

MAILGUN_API_KEY MAILGUN_DOMAIN

ConvertKit

Creator marketing platform.

CONVERTKIT_API_KEY

Postmark

Fast transactional email delivery.

POSTMARK_API_KEY

Agent

Description

Env Vars

Instagram

User profiles, media, and comments via the Instagram Graph API.

INSTAGRAM_ACCESS_TOKEN

TikTok

User profiles, videos, and analytics via the TikTok Open API.

TIKTOK_ACCESS_TOKEN

Reddit

Posts, comments, subreddits, and user information.

REDDIT_CLIENT_ID REDDIT_CLIENT_SECRET REDDIT_USERNAME REDDIT_PASSWORD

YouTube

Channels, playlists, videos, and categories via the YouTube Data API v3.

YOUTUBE_ACCESS_TOKEN or YOUTUBE_API_KEY

Facebook Pages

Posts, photos, comments, and Page insights via the Graph API.

—

LinkedIn

Organic posts, timelines, reshares, and image uploads.

—

Pinterest

Boards, pins, and pin analytics via the Pinterest API v5.

—

Snapchat

Ad accounts, campaigns, ads, and audience insights.

—

Tumblr

Create, edit, and manage posts and blogs via the Tumblr API v2.

—

Twitter / X

Posts, search, timelines, profiles, and media uploads via the X API v2.

—

Agent

Description

Env Vars

Jira

Issues, comments, attachments, users, and workflows. Supports JQL search.

JIRA_BASE_URL JIRA_API_TOKEN JIRA_EMAIL

Notion

Read databases, create pages, and update blocks.

NOTION_TOKEN

Trello

Manage boards, lists, and cards.

TRELLO_API_KEY TRELLO_TOKEN

Asana

Manage tasks and projects.

ASANA_ACCESS_TOKEN

Monday.com

Update items and manage boards.

MONDAY_API_TOKEN

ClickUp

Manage tasks and workspaces.

CLICKUP_API_TOKEN

Todoist

Manage personal and team to-dos.

TODOIST_API_TOKEN

Smartsheet

Manage rows, columns, and sheets.

SMARTSHEET_ACCESS_TOKEN

Agent

Description

Env Vars

Wikidata

SPARQL queries against the Wikidata knowledge base.

—

Agent

Description

Env Vars

Airtable

CRUD operations on bases and records.

AIRTABLE_ACCESS_TOKEN

Evernote

Create and organize notes.

EVERNOTE_TOKEN

Obsidian

Local vault management and markdown generation.

OBSIDIAN_VAULT_PATH

Google Sheets

Read, update, append, and clear spreadsheet data.

GOOGLE_SHEETS_ACCESS_TOKEN

Agent

Description

Env Vars

Salesforce

Manage leads, contacts, and opportunities.

SALESFORCE_INSTANCE_URL SALESFORCE_API_KEY

HubSpot

Inbound marketing and sales workflows.

HUBSPOT_API_KEY

Pipedrive

Sales pipeline management.

PIPEDRIVE_API_TOKEN

Zoho CRM

Lead and inventory management.

ZOHO_CRM_ACCESS_TOKEN

Copper

CRM built for Google Workspace.

COPPER_API_KEY COPPER_USER_EMAIL

Close

Inside sales CRM.

CLOSE_API_KEY

Salesforce Pardot

B2B marketing automation.

PARDOT_API_KEY PARDOT_BUSINESS_UNIT_ID

Agent

Description

Env Vars

Zendesk

Customer support ticket management.

ZENDESK_API_TOKEN ZENDESK_EMAIL ZENDESK_SUBDOMAIN

Freshdesk

Helpdesk automation.

FRESHDESK_API_KEY FRESHDESK_DOMAIN

Intercom

In-app messaging and customer data.

INTERCOM_ACCESS_TOKEN

Agent

Description

Env Vars

Shopify

Products, orders, customers, and inventory via the Shopify Admin API.

—

Shopify Payments

Orders, transactions, payouts, balance, disputes, and refunds.

—

WooCommerce

Products, orders, and customers.

WOOCOMMERCE_STORE_URL WOOCOMMERCE_CONSUMER_KEY WOOCOMMERCE_CONSUMER_SECRET

BigCommerce

Products, orders, and customers.

BIGCOMMERCE_STORE_HASH BIGCOMMERCE_ACCESS_TOKEN

Magento

Products, orders, and customers.

MAGENTO_BASE_URL MAGENTO_ACCESS_TOKEN

PrestaShop

Products, orders, and customers.

PRESTASHOP_STORE_URL PRESTASHOP_API_KEY

Wix Stores

Products, orders, and inventory.

WIX_API_KEY WIX_SITE_ID

Amazon Seller Central

Seller orders, catalog items, and FBA inventory.

AMAZON_SPAPI_ACCESS_TOKEN AMAZON_SELLING_REGION

eBay

Search, seller inventory, and order management.

EBAY_ACCESS_TOKEN

Etsy

Shops, listings, and receipts.

ETSY_API_KEY ETSY_ACCESS_TOKEN

Gumroad

Products, sales, and subscribers.

GUMROAD_ACCESS_TOKEN

Agent

Description

Env Vars

Stripe

Charges, refunds, invoices, subscriptions, and customers.

—

PayPal

Orders, captures, refunds, payouts, and balances.

—

Square

Payments, refunds, orders, subscriptions, and customers.

—

Braintree

Transactions, refunds, vault customers, and subscriptions.

—

Razorpay

Orders, payments, refunds, invoices, and subscriptions.

—

Wise

Quotes, recipients, transfers, and multi-currency balances.

—

QuickBooks

Invoices, customers, payments, sales receipts, and accounts.

—

FreshBooks

Invoices, clients, expenses, payments, and time entries.

—

Xero

Invoices, contacts, payments, accounts, and reports.

—

Agent

Description

Env Vars

AWS S3

Buckets, objects, ACLs, tags, and versions via S3 REST API.

—

Google Cloud Storage

Buckets, objects, metadata, and ACLs.

—

Google Drive

Files, folders, permissions, and metadata.

—

Dropbox

Files, folders, shared links, and metadata.

—

OneDrive

Files, folders, sharing links, and drive metadata.

—

Box

Files, folders, shared links, and metadata.

—

SharePoint

Sites, document libraries, files, and sharing links.

—

Nextcloud

Files and shares via WebDAV and OCS Share API.

—

MediaFire

Files and folders via the MediaFire Core API 1.5.

—

FTP/SFTP

File transfers, directory management, and remote metadata.

—

Agent

Description

Env Vars

Google Analytics

Reports, realtime metrics, properties, and metadata via GA4.

—

Amplitude

Segmentation, analytics queries, and event tracking.

—

Mixpanel

Query, export, and send events.

—

Segment

Sources, destinations, tracking plans, and events.

—

BigQuery

Query datasets and tables in Google BigQuery.

—

Power BI

Workspaces, reports, datasets, and dashboards.

—

Tableau

Sites, workbooks, views, and data sources.

—

Snowflake

Run queries and inspect databases.

—

Databricks

Run SQL, manage jobs, and clusters.

—

PostgreSQL

Query and manage a PostgreSQL database directly.

—

Agent

Description

Env Vars

BambooHR

Employee directory, time-off, and applicant tracking.

—

Greenhouse

Candidates, applications, jobs, and pipeline management.

—

Lever

Opportunities, postings, applications, and pipeline stages.

—

Workable

Jobs, candidates, pipeline stages, and employees.

—

Workday

Workers, organizations, positions, and time tracking.

—

ADP

Workers, pay statements, profiles, and payroll instructions.

—

Gusto

Employees, jobs, payrolls, and pay stubs.

—

Rippling

Employees, departments, teams, and leave requests.

—

Deel

Contracts, payslips, payroll cycles, and employees.

—

SAP SuccessFactors

Persons, jobs, employment, and departments.

—

Agent

Description

Env Vars

OpenAI ChatGPT

Chat, embeddings, and image generation with OpenAI.

OPENAI_API_KEY

Anthropic Claude

Chat with Anthropic Claude models.

ANTHROPIC_API_KEY

Google Gemini

Generate content with Google Gemini models.

GOOGLE_GEMINI_API_KEY

Cohere

Chat and embeddings with Cohere.

COHERE_API_KEY

Hugging Face

Run inference and search models.

HUGGINGFACE_API_TOKEN

Replicate

Run open-source AI models on Replicate.

REPLICATE_API_TOKEN

Midjourney

Generate images with Midjourney.

MIDJOURNEY_BASE_URL MIDJOURNEY_API_KEY

ElevenLabs

Text-to-speech with ElevenLabs voices.

ELEVENLABS_API_KEY

LangChain

Invoke deployed LangChain chains.

LANGCHAIN_API_BASE_URL

Pinecone

Query and upsert vectors in Pinecone indexes.

PINECONE_API_KEY

Agent

Description

Env Vars

Browser

Stealth Chromium browser for web automation, scraping, and screenshots.

—

HTTP

HTTP requests to external APIs and web services.

—

Image

Image processing and manipulation with sharp.

—

Agent

Description

Env Vars

Image to HTML

Transforms a UI image into a single self-contained HTML file with embedded CSS.

—

Image to React

Transforms a UI image into a React component.

—

JavaScript to TypeScript

Convert JavaScript source files into idiomatic TypeScript.

—

TypeScript to JavaScript

Strip TypeScript annotations and produce plain JavaScript.

—

React to Vue 2

Convert React components into Vue 2 Options API components.

—

Vue 2 to React

Convert Vue 2 Options API components into React functional components.

—

React to Vue 3

Convert React components into Vue 3 Composition API components.

—

Vue 3 to React

Convert Vue 3 Composition API components into React functional components.

—

React to Svelte

Convert React components into Svelte components.

—

Svelte to React

Convert Svelte components into React functional components.

—

CSS to SCSS

Convert plain CSS into structured SCSS with nesting and variables.

—

SCSS to CSS

Flatten SCSS files into plain, browser-ready CSS.

—

Comments Remover

Strip comments from source code while preserving functionality.

—

TypeScript Unused Code Remover

Remove unused imports, variables, functions, and types from TypeScript files.

—

JSON to YAML

Convert JSON files into clean YAML.

—

YAML to JSON

Convert YAML files into formatted JSON.

—

HTML to Pug

Convert HTML files into indented Pug templates.

—

Pug to HTML

Expand Pug templates into standard HTML markup.

—

JavaScript to Python

Translate JavaScript source code into Python.

—

Python to JavaScript

Translate Python source code into JavaScript.

—

Architecture

graph TD
    User["User / Application"] -->|prompt | NodeAgent["NodeAgent (Core Engine)"]

    subgraph Core ["NodeAgent Core"]
        NodeAgent -->|1. Build messages | PromptBuilder["Prompt & System Context"]
        NodeAgent -->|2. Dispatch request | Provider["LLM Engine (Ollama Local / Cloud)"]
        Provider -->|3. Return completion | Parser["Output & JSON Parser"]
        Parser -->|4. Detect hallucination & validate | Guardrails["Guardrails & Schema Validator"]
    end

    Guardrails -->|5a. Tool call detected | Dispatcher["Tool Dispatcher"]
    Guardrails -->|5b. Final response | Output["Final Output"]

    subgraph Ecosystem ["Tools & Agent Factories"]
        Dispatcher -->|Execute | AgentFactories["Agent Factories (e.g. createGitHubAgent, createSlackAgent)"]
        AgentFactories -->|Uses | Tools["Toolsets (gitTools, fsTools, shellTools, etc.)"]
    end

    Tools -->|Result | NodeAgent

• NodeAgent — The core class. Manages the conversation loop, tool dispatch, hallucination detection, and JSON output parsing powered by Ollama. (OpenAI, Anthropic, and Gemini integrations are supported via dedicated toolsets.)
• Tool — A typed function wrapper with name, metadata (description + JSON schema), and an async execution function.
• Agent factories — Functions like createGitHubAgent() that wire up the right tools and system prompt for a specific domain.

Installation

npm install n-agents

Environment Setup

Create a .env file in your project root and choose one of the following configurations:

Local Setup

# Required — Local model (gemma4:e2b-mlx for macOS, gemma4:e2b for Windows & Linux)
OLLAMA_LOCAL_MODEL=gemma4:e2b-mlx

# Optional — Local host override (defaults to http://localhost:11434)
# OLLAMA_LOCAL_HOST=http://localhost:11434

Cloud Setup

# Required — Ollama Cloud API key and cloud model
OLLAMA_API_KEY=your_api_key
OLLAMA_CLOUD_MODEL=gemma4:cloud

# Optional — Cloud host override (defaults to https://ollama.com)
# OLLAMA_CLOUD_HOST=https://ollama.com

Quick Start

Using a pre-built agent

import { createWikidataAgent } from "n-agents";

const agent = createWikidataAgent();

const result = await agent.execute({
  instructions: ["List the top 5 largest countries by area."],
  onStep: (step) => console.log(`[Tool] ${step.tool}`),
});

console.dir(result.output, { depth: null });

Creating a custom agent

import { NodeAgent, Tool } from "n-agents";

const greetTool = new Tool(
  "greet",
  async (_ctx, args) => ({ message: `Hello, ${args.name}!` }),
  {
    description: "Greet someone by name",
    schema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" },
      },
      required: ["name"],
    },
  },
);

const agent = new NodeAgent({
  name: "greeter",
  description: "A friendly greeting agent.",
  tools: [greetTool],
});

const result = await agent.execute({
  instructions: ["Greet Alice"],
});

console.log(result.output);
// { summary: "Greeted Alice", data: { message: "Hello, Alice!" }, success: true }

API Reference

NodeAgent

const agent = new NodeAgent(config: AgentConfig);

interface AgentConfig {
  name: string;              // Agent identifier
  description?: string;      // What this agent specializes in
  tools: Tool[];             // Array of tools the agent can call
  model?: string;            // Ollama model override
  systemPrompt?: string;     // Custom system prompt (overrides auto-generated)
  maxIterations?: number;    // Max LLM turns (default: 50)
  projectRoot?: string;      // Working directory for tools (default: ".")
  rateLimitMs?: number;      // Min delay between LLM calls (default: 500)
}

agent.execute()

const result = await agent.execute<R>({
  instructions: string[],        // Natural language task
  onStep?: (step: StepResult) => void,  // Callback after each tool call
  stopOnStepFail?: boolean,      // Abort on first tool failure (default: false)
  debug?: boolean;               // Enable debug logging & verbose mode for tools (default: false)
});

interface AgentResult<R> {
  success: boolean;     // Whether the task completed successfully
  output: R;            // Parsed JSON output from the agent
  steps: StepResult[];  // Full log of every tool call
  iterations: number;   // Number of LLM turns used
  durationMs: number;   // Total wall-clock time
  error?: string;       // Error message if success is false
}

interface StepResult {
  tool: string;                      // Tool name that was called
  args: Record<string, unknown>;     // Arguments passed to the tool
  result: unknown;                   // Tool return value
  success: boolean;                  // Whether the tool call succeeded
  durationMs: number;                // Tool execution time
}

Tool

const tool = new Tool(name: string, fn: ToolFn, metadata: ToolMetadata);

type ToolFn = (ctx: ToolContext, args: Record<string, unknown>) => Promise<unknown>;

interface ToolMetadata {
  description: string;     // Shown to the LLM
  schema: ToolSchema;      // JSON Schema for arguments
}

interface ToolContext {
  projectRoot: string;     // Resolved working directory
  env: Record<string, string | undefined>;  // Process environment
}

Customizing Agents

Every factory function accepts a partial override object, so you can tune any agent without forking:

import { createGitHubAgent } from "n-agents";

const agent = createGitHubAgent({
  maxIterations: 100, // Allow more turns for complex tasks
  rateLimitMs: 1000, // Slower rate limit
  projectRoot: "/my/repo", // Custom working directory
});

Error Handling

The library exports three error classes for typed error handling:

import { AgentError, ToolExecutionError, ConfigurationError } from "n-agents";

// AgentError           — Base class for all agent errors
// ToolExecutionError   — Thrown when a tool call fails (includes .toolName)
// ConfigurationError   — Thrown for missing API keys or invalid config

Running Examples

Run the included examples with:

# Query Wikidata for the top 5 largest countries
npm run example:wikidata

# Scrape the top 10 Hacker News stories with the stealth browser
npm run example:browser

Project Structure

n-agents/
├── agent.ts           # NodeAgent core — conversation loop, tool dispatch, LLM integration
├── tool.ts            # Tool class — wraps typed functions for LLM consumption
├── types.ts           # Shared TypeScript interfaces (AgentConfig, AgentResult, etc.)
├── errors.ts          # Custom error classes (AgentError, ToolExecutionError, ConfigurationError)
├── index.ts           # Public API — re-exports all agents, tools, types, and errors
├── agents/            # Agent factory functions (one per service)
│   ├── github.ts
│   ├── gitlab.ts
│   ├── bitbucket.ts
│   ├── git.ts
│   ├── data/
│   │   └── wikidata.ts
│   ├── reddit.ts
│   ├── youtube.ts
│   ├── gmail.ts
│   ├── slack.ts
│   ├── jira.ts
│   ├── instagram.ts
│   ├── tiktok.ts
│   ├── browser.ts
│   ├── http.ts
│   ├── google-sheets.ts
│   └── index.ts       # AGENTS_DEF — registry of all instantiated agents
├── tools/             # Tool implementations (one per service + utilities)
│   ├── github.ts      # 93K — comprehensive GitHub API coverage
│   ├── browser.ts     # 69K — stealth Puppeteer automation
│   ├── slack.ts       # 41K — full Slack API integration
│   ├── youtube.ts     # 35K — YouTube Data API v3
│   ├── jira.ts        # 32K — Jira REST API
│   ├── gmail.ts       # 27K — Gmail API
│   ├── reddit.ts      # 24K — Reddit API
│   ├── bitbucket.ts   # 22K — Bitbucket API
│   ├── gitlab.ts      # 20K — GitLab API
│   ├── git.ts         # 17K — local git operations
│   ├── data/
│   │   └── wikidata.ts    # 8K  — SPARQL + entity search
│   ├── instagram.ts   # 5K  — Instagram Graph API
│   ├── tiktok.ts      # 5K  — TikTok Open API
│   ├── fs.ts          # 4K  — filesystem operations
│   ├── shell.ts       # 2K  — shell command execution
│   ├── http.ts        # HTTP requests
│   ├── google-sheets.ts # Google Sheets API
│   └── index.ts       # Tool set re-exports
├── utils/
│   └── stealth-browser.ts  # 43K — Puppeteer stealth setup with ghost-cursor
├── examples/
│   ├── wikidata.ts    # Query Wikidata with natural language
│   └── browser.ts     # Scrape Hacker News top stories
└── scripts/             # Utility scripts

Contributing

Contributions are welcome! If you'd like to add a new agent, improve an existing tool, or fix a bug, please open an issue or pull request on GitHub.

Sponsors

This project is made possible by the support of our sponsors.

Name

Your logo here

License

n-agents is released under the MIT License