Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/vgulerianb/agents-js

A versatile JavaScript library for designing and managing intelligent agents capable of interacting with AI-driven chat models, leveraging OpenAI's GPT for dynamic conversations and task automation.",
https://github.com/vgulerianb/agents-js

agents ai multiagent-systems openai swarm

Last synced: 5 months ago
JSON representation

A versatile JavaScript library for designing and managing intelligent agents capable of interacting with AI-driven chat models, leveraging OpenAI's GPT for dynamic conversations and task automation.",

Awesome Lists containing this project

README 

          
# agents-js



A powerful JavaScript library for building and orchestrating AI agents with OpenAI's GPT models.



## Installation



```bash

npm install agents-js

```



## Features



- 🤖 **Multi-Agent Orchestration** - Coordinate multiple specialized agents

- 🔄 **Automatic Agent Transfers** - Seamless handoffs between agents

- 🛠️ **Pre-built Tools** - Web search (Serper, Firecrawl), calculations, time utilities

- 📊 **Token Tracking** - Monitor token usage across conversations

- 🔐 **Session Management** - Persistent conversation state

- ⚡ **Streaming Support** - Real-time response generation

- 🎯 **Lifecycle Hooks** - `beforeModel`, `afterModel`, `beforeTool`, `afterTool`

- ✅ **Tool Confirmation** - Human-in-the-loop for sensitive operations

- 📝 **TypeScript Support** - Full type definitions included

- 📋 **Detailed Logging** - Track agent transfers and tool calls



## Quick Start



### Basic Agent



```javascript

require("dotenv").config();

const { Agent, AgentController } = require("agents-js");

const { calculate, getCurrentTime } = require("agents-js/tools");

const OpenAI = require("openai");



const client = new OpenAI({

  apiKey: process.env.OPENAI_API_KEY,

});



const controller = new AgentController(client);



const agent = new Agent({

  name: "Assistant",

  model: "gpt-4o-mini",

  instructions: "You are a helpful assistant.",

  functions: [calculate, getCurrentTime],

});



const response = await controller.run(agent, [

  { role: "user", content: "What is 25 * 4?" },

]);



console.log(response.messages[response.messages.length - 1].content);

```



### Multi-Agent System with Sub-Agents



```javascript

require("dotenv").config();

const { Agent, AgentController } = require("agents-js");

const { serperSearch, calculate, getCurrentTime } = require("agents-js/tools");

const OpenAI = require("openai");



const client = new OpenAI({

  apiKey: process.env.OPENAI_API_KEY,

});



// Create specialized agents

const weatherAgent = new Agent({

  name: "WeatherSpecialist",

  model: "gpt-4o-mini",

  instructions:

    "You are a weather expert. Use serperSearch to find weather information.",

  functions: [serperSearch],

});



const mathAgent = new Agent({

  name: "MathSpecialist",

  model: "gpt-4o-mini",

  instructions: "You are a math expert. Use calculate for all calculations.",

  functions: [calculate],

});



const timeAgent = new Agent({

  name: "TimeSpecialist",

  model: "gpt-4o-mini",

  instructions:

    "You are a time expert. Use getCurrentTime to tell the current time.",

  functions: [getCurrentTime],

});



// Create main coordinator agent with sub-agents

const mainAgent = new Agent({

  name: "Assistant",

  model: "gpt-4o-mini",

  instructions: `You are a helpful coordinator. Route requests to specialists:

  - Weather questions → WeatherSpecialist

  - Math problems → MathSpecialist  

  - Time questions → TimeSpecialist`,

  subAgents: [weatherAgent, mathAgent, timeAgent],

});



const controller = new AgentController(client, {

  apiKeys: {

    serper: process.env.SERPER_API_KEY,

  },

});



// The controller will automatically transfer between agents

const response = await controller.run(mainAgent, [

  { role: "user", content: "What's the weather in Tokyo?" },

]);



console.log(response.messages[response.messages.length - 1].content);



// Export for playground

module.exports = { mainAgent, weatherAgent, mathAgent, timeAgent };

```



## Pre-built Tools



agents-js comes with several pre-built tools:



### Web Search & Scraping



```javascript

const {

  serperSearch,

  firecrawlSearch,

  firecrawlScrape,

} = require("agents-js/tools");



// Serper.dev web search (requires SERPER_API_KEY)

// Automatically falls back to Firecrawl if Serper key is missing



// Firecrawl web search (requires FIRECRAWL_API_KEY)

// Firecrawl web scraping

```



### Calculations & Time



```javascript

const {

  calculate,

  getCurrentTime,

  getTimestamp,

  formatDate,

} = require("agents-js/tools");

```



## Advanced Features



### Lifecycle Hooks



```javascript

const agent = new Agent({

  name: "Assistant",

  model: "gpt-4o-mini",

  instructions: "You are helpful.",

  functions: [calculate],

  beforeModel: async (messages, contextVariables) => {

    console.log("📤 Sending to model:", messages.length, "messages");

  },

  afterModel: async (response, contextVariables) => {

    console.log("📥 Received from model");

  },

  beforeTool: async (toolName, args, contextVariables) => {

    console.log("🔧 Calling tool:", toolName);

  },

  afterTool: async (toolName, args, result, contextVariables) => {

    console.log("✅ Tool completed:", toolName);

  },

});

```



### Session Management



```javascript

const { Session } = require("agents-js");



const session = new Session();



// Store conversation state

session.set("user_name", "John");

session.set("preferences", { theme: "dark" });



// Retrieve state

const userName = session.get("user_name");



// Pass session in context

const response = await controller.run(agent, messages, {

  session: session,

});

```



### Tool Confirmation (Human-in-the-Loop)



```javascript

const { ToolConfirmation } = require("agents-js");



function dangerousOperation({ action }) {

  // Sensitive operation

  return `Executed: ${action}`;

}



const agent = new Agent({

  name: "Assistant",

  model: "gpt-4o-mini",

  instructions: "You are helpful.",

  functions: [

    new ToolConfirmation({

      tool: dangerousOperation,

      message: "This action is sensitive. Confirm?",

      autoConfirm: false,

    }),

  ],

});



const controller = new AgentController(client, {

  confirmationHandler: async (toolName, args, message) => {

    console.log(`Confirm ${toolName}?`, args);

    return true; // or false to cancel

  },

});

```



### Disable Logging



```javascript

const controller = new AgentController(client, {

  enableLogging: false, // Disable automatic logging

});

```



## Testing with Playground



Test your agents interactively with the playground:



```bash



# Run with your agents file

npx agents-playground ./my-agents.js

```



The playground provides:



- 🎨 Beautiful chat interface

- 📊 Real-time token tracking

- 🔄 Agent transfer visualization

- 🔧 Environment variable management

- 📝 Detailed execution logs



## Examples



Check out the [examples directory](https://github.com/vgulerianb/agents-js/tree/main/examples) for complete working examples:



- **[basic-agent.js](https://github.com/vgulerianb/agents-js/blob/main/examples/basic-agent.js)** - Simple agent with tools

- **[multi-agent-system.js](https://github.com/vgulerianb/agents-js/blob/main/examples/multi-agent-system.js)** - Coordinator with specialized sub-agents

- **[advanced-features.js](https://github.com/vgulerianb/agents-js/blob/main/examples/advanced-features.js)** - Lifecycle hooks, sessions, and tool confirmation

- **[subagents-parallel.js](https://github.com/vgulerianb/agents-js/blob/main/examples/subagents-parallel.js)** - Complex multi-agent coordination

- **[subagents-parallel-streaming.js](https://github.com/vgulerianb/agents-js/blob/main/examples/subagents-parallel-streaming.js)** - Streaming with multiple agents



### Running Examples



```bash

# Clone the repository

git clone https://github.com/vgulerianb/agents-js.git

cd agents-js



# Install dependencies

npm install

cd packages/agents-js

npm link



# Set up environment variables

cp .env.example .env

# Edit .env with your API keys



# Run an example

node examples/basic-agent.js



# Or test with playground

npx agents-playground examples/multi-agent-system.js

```



## API Reference



### Agent



```typescript

new Agent({

  name: string;

  model: string;

  instructions: string | ((context) => string);

  functions?: Function[];

  subAgents?: Agent[];

  parallelToolCalls?: boolean;

  beforeModel?: (messages, context) => Promise;

  afterModel?: (response, context) => Promise;

  beforeTool?: (toolName, args, context) => Promise;

  afterTool?: (toolName, args, result, context) => Promise;

});

```



### AgentController



```typescript

new AgentController(client: OpenAI, options?: {

  confirmationHandler?: (toolName, args, message) => Promise;

  apiKeys?: Record;

  enableLogging?: boolean;

});

```



### Result



```typescript

new Result({

  value: string;

  agent?: Agent;

  agentName?: string;

  contextVariables?: Record;

});

```



## Environment Variables



Create a `.env` file:



```env

# OpenAI Configuration

OPENAI_API_KEY=your_openai_api_key

OPENAI_BASE_URL=https://api.openai.com/v1  # Optional



# External Tool API Keys

SERPER_API_KEY=your_serper_api_key  # Optional, for web search

FIRECRAWL_API_KEY=your_firecrawl_api_key  # Optional, for web scraping

```



## TypeScript Support



Full TypeScript definitions are included:



```typescript

import { Agent, AgentController, Result, Session } from "agents-js";

import { serperSearch, calculate } from "agents-js/tools";

```



## License



MIT © Vikrant Guleria



## Links



- [GitHub Repository](https://github.com/vgulerianb/agents-js)

- [npm Package](https://www.npmjs.com/package/agents-js)

- [Playground Package](https://www.npmjs.com/package/agents-playground)

- [Report Issues](https://github.com/vgulerianb/agents-js/issues)



## Contributing



Contributions are welcome! Please feel free to submit a Pull Request.