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.
A powerful JavaScript library for building and orchestrating AI agents with OpenAI's GPT models.
npm install agents-js
beforeModel, afterModel, beforeTool, afterToolrequire("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);
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 };
agents-js comes with several pre-built tools:
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
const {
calculate,
getCurrentTime,
getTimestamp,
formatDate,
} = require("agents-js/tools");
agents-js supports integration with Model Context Protocol (MCP) servers, allowing you to connect to any MCP-compatible tool server and use its tools seamlessly with your agents.
Connect to the Zomato MCP server for food ordering capabilities:
const { connectMCPServer } = require("agents-js/tools");
// Connect to Zomato using mcp-remote (for HTTP-based MCP servers)
// Requires: npm install -g mcp-remote
const zomatoTools = await connectMCPServer(
"zomato",
"npx",
["-y", "mcp-remote", "https://mcp-server.zomato.com/mcp"]
);
// Use MCP tools with your agent
const foodAgent = new Agent({
name: "FoodOrderingAssistant",
model: "gpt-4o-mini",
instructions: "You are a food ordering assistant powered by Zomato.",
functions: zomatoTools, // MCP tools work just like built-in tools!
});
For local stdio-based MCP servers:
const { connectMCPServer } = require("agents-js/tools");
// Connect to a local MCP server (e.g., filesystem)
const mcpTools = await connectMCPServer("filesystem", "npx", [
"-y",
"@modelcontextprotocol/server-filesystem",
"/tmp",
]);
Note: HTTP-based MCP servers (like Zomato) require mcp-remote as a proxy. Install it with:
npm install -g mcp-remote
const {
connectMCPServer, // Connect to stdio-based MCP server
connectMCPServerHTTP, // Connect to HTTP-based MCP server
disconnectMCPServer, // Disconnect a specific server
disconnectAllMCPServers, // Disconnect all servers
getMCPManager, // Get manager for advanced usage
} = require("agents-js/tools");
const { connectMCPServer } = require("agents-js/tools");
const { calculate, getCurrentTime } = require("agents-js/tools");
// Connect to Zomato MCP server using mcp-remote
const zomatoTools = await connectMCPServer(
"zomato",
"npx",
["-y", "mcp-remote", "https://mcp-server.zomato.com/mcp"]
);
// Combine with built-in tools
const agent = new Agent({
name: "HybridAssistant",
model: "gpt-4o-mini",
instructions: "You have food ordering, calculation, and time capabilities.",
functions: [...zomatoTools, calculate, getCurrentTime],
});
For more control, use the MCP Manager directly:
const { getMCPManager } = require("agents-js/tools");
const mcpManager = getMCPManager();
// Connect to HTTP-based servers using mcp-remote
await mcpManager.connectStdio("zomato", "npx", [
"-y",
"mcp-remote",
"https://mcp-server.zomato.com/mcp"
]);
// Connect to local stdio-based servers
await mcpManager.connectStdio("filesystem", "npx", [
"-y",
"@modelcontextprotocol/server-filesystem",
"/tmp",
]);
// Get all tools from all servers
const allTools = mcpManager.getAllToolFunctions();
// Get tools from a specific server
const zomatoTools = mcpManager.getToolFunctions("zomato");
// Disconnect specific servers
await mcpManager.disconnect("zomato");
You can use any MCP-compatible server:
HTTP-based servers (requires mcp-remote):
First install mcp-remote:
npm install -g mcp-remote
Then connect to servers like:
Stdio-based servers (local install):
# Filesystem access
npm install -g @modelcontextprotocol/server-filesystem
# SQLite database
npm install -g @modelcontextprotocol/server-sqlite
# GitHub integration
npm install -g @modelcontextprotocol/server-github
See examples/mcp-integration.js for complete working examples.
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);
},
});
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,
});
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
},
});
const controller = new AgentController(client, {
enableLogging: false, // Disable automatic logging
});
Test your agents interactively with the playground:
# Install playground globally
npm install -g agents-playground
# Run with your agents file
npx agents-playground ./my-agents.js
The playground provides:
Check out the examples directory for complete working examples:
# 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
new Agent({
name: string;
model: string;
instructions: string | ((context) => string);
functions?: Function[];
subAgents?: Agent[];
parallelToolCalls?: boolean;
beforeModel?: (messages, context) => Promise<void>;
afterModel?: (response, context) => Promise<void>;
beforeTool?: (toolName, args, context) => Promise<boolean | void>;
afterTool?: (toolName, args, result, context) => Promise<void>;
});
new AgentController(client: OpenAI, options?: {
confirmationHandler?: (toolName, args, message) => Promise<boolean>;
apiKeys?: Record<string, string>;
enableLogging?: boolean;
});
new Result({
value: string;
agent?: Agent;
agentName?: string;
contextVariables?: Record<string, any>;
});
Create a .env file:
# 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
Full TypeScript definitions are included:
import { Agent, AgentController, Result, Session } from "agents-js";
import { serperSearch, calculate } from "agents-js/tools";
MIT © Vikrant Guleria
Contributions are welcome! Please feel free to submit a Pull Request.
FAQs
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.
We found that agents-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.