{"id":21994944,"url":"https://github.com/vgulerianb/agents-js","last_synced_at":"2026-02-02T16:04:01.686Z","repository":{"id":261961014,"uuid":"885837483","full_name":"vgulerianb/agents-js","owner":"vgulerianb","description":"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.\",","archived":false,"fork":false,"pushed_at":"2024-11-15T16:24:40.000Z","size":13,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T17:17:55.258Z","etag":null,"topics":["agents","ai","multiagent-systems","openai","swarm"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vgulerianb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-09T14:27:19.000Z","updated_at":"2024-11-15T20:31:10.000Z","dependencies_parsed_at":"2024-11-09T15:29:20.104Z","dependency_job_id":"aa14c5ea-ef0f-4a78-b4a4-847b9be73802","html_url":"https://github.com/vgulerianb/agents-js","commit_stats":null,"previous_names":["vgulerianb/agents-js"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vgulerianb%2Fagents-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vgulerianb%2Fagents-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vgulerianb%2Fagents-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vgulerianb%2Fagents-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vgulerianb","download_url":"https://codeload.github.com/vgulerianb/agents-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251750368,"owners_count":21637710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","multiagent-systems","openai","swarm"],"created_at":"2024-11-29T21:11:28.172Z","updated_at":"2026-02-02T16:04:01.680Z","avatar_url":"https://github.com/vgulerianb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agents-js\n\nA powerful JavaScript library for building and orchestrating AI agents with OpenAI's GPT models.\n\n## Installation\n\n```bash\nnpm install agents-js\n```\n\n## Features\n\n- 🤖 **Multi-Agent Orchestration** - Coordinate multiple specialized agents\n- 🔄 **Automatic Agent Transfers** - Seamless handoffs between agents\n- 🛠️ **Pre-built Tools** - Web search (Serper, Firecrawl), calculations, time utilities\n- 📊 **Token Tracking** - Monitor token usage across conversations\n- 🔐 **Session Management** - Persistent conversation state\n- ⚡ **Streaming Support** - Real-time response generation\n- 🎯 **Lifecycle Hooks** - `beforeModel`, `afterModel`, `beforeTool`, `afterTool`\n- ✅ **Tool Confirmation** - Human-in-the-loop for sensitive operations\n- 📝 **TypeScript Support** - Full type definitions included\n- 📋 **Detailed Logging** - Track agent transfers and tool calls\n\n## Quick Start\n\n### Basic Agent\n\n```javascript\nrequire(\"dotenv\").config();\nconst { Agent, AgentController } = require(\"agents-js\");\nconst { calculate, getCurrentTime } = require(\"agents-js/tools\");\nconst OpenAI = require(\"openai\");\n\nconst client = new OpenAI({\n  apiKey: process.env.OPENAI_API_KEY,\n});\n\nconst controller = new AgentController(client);\n\nconst agent = new Agent({\n  name: \"Assistant\",\n  model: \"gpt-4o-mini\",\n  instructions: \"You are a helpful assistant.\",\n  functions: [calculate, getCurrentTime],\n});\n\nconst response = await controller.run(agent, [\n  { role: \"user\", content: \"What is 25 * 4?\" },\n]);\n\nconsole.log(response.messages[response.messages.length - 1].content);\n```\n\n### Multi-Agent System with Sub-Agents\n\n```javascript\nrequire(\"dotenv\").config();\nconst { Agent, AgentController } = require(\"agents-js\");\nconst { serperSearch, calculate, getCurrentTime } = require(\"agents-js/tools\");\nconst OpenAI = require(\"openai\");\n\nconst client = new OpenAI({\n  apiKey: process.env.OPENAI_API_KEY,\n});\n\n// Create specialized agents\nconst weatherAgent = new Agent({\n  name: \"WeatherSpecialist\",\n  model: \"gpt-4o-mini\",\n  instructions:\n    \"You are a weather expert. Use serperSearch to find weather information.\",\n  functions: [serperSearch],\n});\n\nconst mathAgent = new Agent({\n  name: \"MathSpecialist\",\n  model: \"gpt-4o-mini\",\n  instructions: \"You are a math expert. Use calculate for all calculations.\",\n  functions: [calculate],\n});\n\nconst timeAgent = new Agent({\n  name: \"TimeSpecialist\",\n  model: \"gpt-4o-mini\",\n  instructions:\n    \"You are a time expert. Use getCurrentTime to tell the current time.\",\n  functions: [getCurrentTime],\n});\n\n// Create main coordinator agent with sub-agents\nconst mainAgent = new Agent({\n  name: \"Assistant\",\n  model: \"gpt-4o-mini\",\n  instructions: `You are a helpful coordinator. Route requests to specialists:\n  - Weather questions → WeatherSpecialist\n  - Math problems → MathSpecialist  \n  - Time questions → TimeSpecialist`,\n  subAgents: [weatherAgent, mathAgent, timeAgent],\n});\n\nconst controller = new AgentController(client, {\n  apiKeys: {\n    serper: process.env.SERPER_API_KEY,\n  },\n});\n\n// The controller will automatically transfer between agents\nconst response = await controller.run(mainAgent, [\n  { role: \"user\", content: \"What's the weather in Tokyo?\" },\n]);\n\nconsole.log(response.messages[response.messages.length - 1].content);\n\n// Export for playground\nmodule.exports = { mainAgent, weatherAgent, mathAgent, timeAgent };\n```\n\n## Pre-built Tools\n\nagents-js comes with several pre-built tools:\n\n### Web Search \u0026 Scraping\n\n```javascript\nconst {\n  serperSearch,\n  firecrawlSearch,\n  firecrawlScrape,\n} = require(\"agents-js/tools\");\n\n// Serper.dev web search (requires SERPER_API_KEY)\n// Automatically falls back to Firecrawl if Serper key is missing\n\n// Firecrawl web search (requires FIRECRAWL_API_KEY)\n// Firecrawl web scraping\n```\n\n### Calculations \u0026 Time\n\n```javascript\nconst {\n  calculate,\n  getCurrentTime,\n  getTimestamp,\n  formatDate,\n} = require(\"agents-js/tools\");\n```\n\n## Advanced Features\n\n### Lifecycle Hooks\n\n```javascript\nconst agent = new Agent({\n  name: \"Assistant\",\n  model: \"gpt-4o-mini\",\n  instructions: \"You are helpful.\",\n  functions: [calculate],\n  beforeModel: async (messages, contextVariables) =\u003e {\n    console.log(\"📤 Sending to model:\", messages.length, \"messages\");\n  },\n  afterModel: async (response, contextVariables) =\u003e {\n    console.log(\"📥 Received from model\");\n  },\n  beforeTool: async (toolName, args, contextVariables) =\u003e {\n    console.log(\"🔧 Calling tool:\", toolName);\n  },\n  afterTool: async (toolName, args, result, contextVariables) =\u003e {\n    console.log(\"✅ Tool completed:\", toolName);\n  },\n});\n```\n\n### Session Management\n\n```javascript\nconst { Session } = require(\"agents-js\");\n\nconst session = new Session();\n\n// Store conversation state\nsession.set(\"user_name\", \"John\");\nsession.set(\"preferences\", { theme: \"dark\" });\n\n// Retrieve state\nconst userName = session.get(\"user_name\");\n\n// Pass session in context\nconst response = await controller.run(agent, messages, {\n  session: session,\n});\n```\n\n### Tool Confirmation (Human-in-the-Loop)\n\n```javascript\nconst { ToolConfirmation } = require(\"agents-js\");\n\nfunction dangerousOperation({ action }) {\n  // Sensitive operation\n  return `Executed: ${action}`;\n}\n\nconst agent = new Agent({\n  name: \"Assistant\",\n  model: \"gpt-4o-mini\",\n  instructions: \"You are helpful.\",\n  functions: [\n    new ToolConfirmation({\n      tool: dangerousOperation,\n      message: \"This action is sensitive. Confirm?\",\n      autoConfirm: false,\n    }),\n  ],\n});\n\nconst controller = new AgentController(client, {\n  confirmationHandler: async (toolName, args, message) =\u003e {\n    console.log(`Confirm ${toolName}?`, args);\n    return true; // or false to cancel\n  },\n});\n```\n\n### Disable Logging\n\n```javascript\nconst controller = new AgentController(client, {\n  enableLogging: false, // Disable automatic logging\n});\n```\n\n## Testing with Playground\n\nTest your agents interactively with the playground:\n\n```bash\n\n# Run with your agents file\nnpx agents-playground ./my-agents.js\n```\n\nThe playground provides:\n\n- 🎨 Beautiful chat interface\n- 📊 Real-time token tracking\n- 🔄 Agent transfer visualization\n- 🔧 Environment variable management\n- 📝 Detailed execution logs\n\n## Examples\n\nCheck out the [examples directory](https://github.com/vgulerianb/agents-js/tree/main/examples) for complete working examples:\n\n- **[basic-agent.js](https://github.com/vgulerianb/agents-js/blob/main/examples/basic-agent.js)** - Simple agent with tools\n- **[multi-agent-system.js](https://github.com/vgulerianb/agents-js/blob/main/examples/multi-agent-system.js)** - Coordinator with specialized sub-agents\n- **[advanced-features.js](https://github.com/vgulerianb/agents-js/blob/main/examples/advanced-features.js)** - Lifecycle hooks, sessions, and tool confirmation\n- **[subagents-parallel.js](https://github.com/vgulerianb/agents-js/blob/main/examples/subagents-parallel.js)** - Complex multi-agent coordination\n- **[subagents-parallel-streaming.js](https://github.com/vgulerianb/agents-js/blob/main/examples/subagents-parallel-streaming.js)** - Streaming with multiple agents\n\n### Running Examples\n\n```bash\n# Clone the repository\ngit clone https://github.com/vgulerianb/agents-js.git\ncd agents-js\n\n# Install dependencies\nnpm install\ncd packages/agents-js\nnpm link\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your API keys\n\n# Run an example\nnode examples/basic-agent.js\n\n# Or test with playground\nnpx agents-playground examples/multi-agent-system.js\n```\n\n## API Reference\n\n### Agent\n\n```typescript\nnew Agent({\n  name: string;\n  model: string;\n  instructions: string | ((context) =\u003e string);\n  functions?: Function[];\n  subAgents?: Agent[];\n  parallelToolCalls?: boolean;\n  beforeModel?: (messages, context) =\u003e Promise\u003cvoid\u003e;\n  afterModel?: (response, context) =\u003e Promise\u003cvoid\u003e;\n  beforeTool?: (toolName, args, context) =\u003e Promise\u003cboolean | void\u003e;\n  afterTool?: (toolName, args, result, context) =\u003e Promise\u003cvoid\u003e;\n});\n```\n\n### AgentController\n\n```typescript\nnew AgentController(client: OpenAI, options?: {\n  confirmationHandler?: (toolName, args, message) =\u003e Promise\u003cboolean\u003e;\n  apiKeys?: Record\u003cstring, string\u003e;\n  enableLogging?: boolean;\n});\n```\n\n### Result\n\n```typescript\nnew Result({\n  value: string;\n  agent?: Agent;\n  agentName?: string;\n  contextVariables?: Record\u003cstring, any\u003e;\n});\n```\n\n## Environment Variables\n\nCreate a `.env` file:\n\n```env\n# OpenAI Configuration\nOPENAI_API_KEY=your_openai_api_key\nOPENAI_BASE_URL=https://api.openai.com/v1  # Optional\n\n# External Tool API Keys\nSERPER_API_KEY=your_serper_api_key  # Optional, for web search\nFIRECRAWL_API_KEY=your_firecrawl_api_key  # Optional, for web scraping\n```\n\n## TypeScript Support\n\nFull TypeScript definitions are included:\n\n```typescript\nimport { Agent, AgentController, Result, Session } from \"agents-js\";\nimport { serperSearch, calculate } from \"agents-js/tools\";\n```\n\n## License\n\nMIT © Vikrant Guleria\n\n## Links\n\n- [GitHub Repository](https://github.com/vgulerianb/agents-js)\n- [npm Package](https://www.npmjs.com/package/agents-js)\n- [Playground Package](https://www.npmjs.com/package/agents-playground)\n- [Report Issues](https://github.com/vgulerianb/agents-js/issues)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvgulerianb%2Fagents-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvgulerianb%2Fagents-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvgulerianb%2Fagents-js/lists"}