SwarmJS-Node is a TypeScript library implementation that o1-mini
generated from OpenAI's Swarm repository.
- Agent Management: Define and manage multiple agents with distinct behaviors and functions.
- Function Calls: Extend agent capabilities by integrating custom functions.
- Streaming Responses: Handle and display streaming responses from the Swarm API.
- Debugging: Enable debug mode for detailed logging and troubleshooting.
- TypeScript Support: Fully typed library for enhanced developer experience and type safety.
- Environment Variable Management: Securely handle sensitive information using environment variables.
Ensure you have Node.js installed. Then, install swarmjs-node
via npm:
npm install swarmjs-node
Or using pnpm:
pnpm add swarmjs-node
- OpenAI API Key: You'll need an OpenAI API key to interact with the Swarm API. Sign up at OpenAI if you haven't already.
Below is a simple example demonstrating how to initialize the Swarm client, define agents with custom functions, and run a demo loop.
-
Clone the Repository:
git clone https://github.com/ColeMurray/swarmjs.git cd swarmjs
-
Install Dependencies:
The project uses
pnpm
. If you don't have it installed, you can install it globally:npm install -g pnpm
Then, install the project dependencies:
pnpm install
-
Build the Project:
Compile the TypeScript code to JavaScript:
pnpm run build
-
Configure Environment Variables:
Create a
.env
file in the root directory and add your OpenAI API key:OPENAI_API_KEY=your_openai_api_key_here
Note: Ensure that
.env
is listed in your.gitignore
to prevent accidental commits of sensitive information.
An example script is provided in the examples
directory. Here's how to set it up and run it.
// Filename: examples/main.ts
import { Agent, AgentFunction } from '../swarm';
import { runDemoLoop } from '../swarm/repl';
import * as dotenv from 'dotenv';
// Load environment variables from .env file
dotenv.config();
// Define an addition function
const addFunction: AgentFunction = {
name: 'add',
func: ({ a, b }) => {
return (a + b).toString();
},
descriptor: {
name: 'add',
description: 'Adds two numbers together.',
parameters: {
a: { type: 'number', required: true, description: 'The first number to add.' },
b: { type: 'number', required: true, description: 'The second number to add.' },
},
},
};
// Define a subtraction function
const subFunction: AgentFunction = {
name: 'sub',
func: ({ a, b }) => {
return (a - b).toString();
},
descriptor: {
name: 'sub',
description: 'Subtracts two numbers.',
parameters: {
a: { type: 'number', required: true, description: 'The first number.' },
b: { type: 'number', required: true, description: 'The second number.' },
},
},
};
// Define a function to transfer to another agent
const transferToHaikuAgent: AgentFunction = {
name: 'transfer_to_haiku_agent',
func: () => {
return agentB;
},
descriptor: {
name: 'transfer_to_haiku_agent',
description: 'Transfers the conversation to the Haiku Agent.',
parameters: {},
},
};
// Initialize a Haiku Agent
const agentB = new Agent({
name: 'HaikuAgent',
model: 'gpt-4o-mini',
instructions: 'You only respond in haikus.',
});
// Initialize the Helper Agent with functions
const agent = new Agent({
name: 'HelperAgent',
model: 'gpt-4o-mini',
instructions: 'You are a helpful assistant.',
functions: [transferToHaikuAgent, addFunction, subFunction],
});
// Run the demo loop
runDemoLoop(agent, undefined, true, true).catch(error => {
console.error('Error running demo loop:', error);
});
-
Ensure the Project is Built:
pnpm run build
-
Run the Example Script:
pnpm run start:example
Expected Output:
Starting Swarm CLI 🐝 User: Hello HelperAgent: Hello! How can I assist you today? User: Add 5 and 3 HelperAgent: The result of adding 5 and 3 is 8. User: Subtract 10 from 15 HelperAgent: The result of subtracting 10 from 15 is 5. User: Exit Exiting Swarm CLI.
Note: The actual responses may vary based on the implementation and interactions with the OpenAI API.
For more comprehensive examples and advanced use cases, refer to the examples directory in the repository. You can modify these examples to suit your specific needs or to explore additional functionalities provided by SwarmJS-Node.
import { Swarm, Agent, AgentFunction } from 'swarmjs-node';
Agent functions extend the capabilities of your agents by allowing them to perform specific tasks.
const multiplyFunction: AgentFunction = {
name: 'multiply',
func: ({ a, b }) => {
return (a * b).toString();
},
descriptor: {
name: 'multiply',
description: 'Multiplies two numbers.',
parameters: {
a: { type: 'number', required: true, description: 'The first number.' },
b: { type: 'number', required: true, description: 'The second number.' },
},
},
};
The runDemoLoop
function initializes the interactive CLI for engaging with the Swarm API.
import { runDemoLoop } from 'swarmjs-node/repl';
const agent = new Agent({
name: 'CalculatorAgent',
model: 'gpt-4o-mini',
instructions: 'You are a calculator agent that can perform basic arithmetic operations.',
functions: [addFunction, subFunction, multiplyFunction],
});
runDemoLoop(agent, undefined, true, true).catch(error => {
console.error('Error running demo loop:', error);
});
Comprehensive API documentation is available here. This includes detailed descriptions of classes, methods, and interfaces provided by SwarmJS-Node.
-
API Keys: Ensure that your OpenAI API key is kept secure. Do not commit your
.env
file or API keys to version control. Use environment variables to manage sensitive information. - Dependencies: Regularly update dependencies to patch any known vulnerabilities.
SwarmJS-Node includes a testing setup using Jest. To run the tests:
-
Install Development Dependencies:
pnpm install
-
Run Tests:
pnpm run test
-
Run Tests with Coverage:
pnpm run test -- --coverage
Ensure code quality and consistency by running ESLint.
-
Check for Linting Errors:
pnpm run lint
-
Automatically Fix Linting Errors:
pnpm run lint:fix
Compile TypeScript source files to JavaScript:
pnpm run build
-
Define Agent Functions:
Create new
AgentFunction
objects with appropriatename
,func
, anddescriptor
. -
Update Agents:
Initialize or update
Agent
instances with the new functions. -
Run and Test:
Use the example scripts or create new ones in the
examples
directory to test the new features.
Regularly run linting and testing to maintain code quality.
pnpm run lint
pnpm run test
Contributions are welcome! Please follow these steps to contribute:
-
Fork the Repository:
Click the "Fork" button at the top right of the repository page.
-
Clone Your Fork:
git clone https://github.com/ColeMurray/swarmjs-node.git cd swarmjs-node
-
Create a New Branch:
git checkout -b feature/YourFeatureName
-
Make Your Changes:
Implement your feature or bug fix.
-
Commit Your Changes:
git commit -m "Add feature: YourFeatureName"
-
Push to Your Fork:
git push origin feature/YourFeatureName
-
Create a Pull Request:
Navigate to the original repository and click "Compare & pull request."
Please ensure that your contributions adhere to the following guidelines:
- Code Quality: Follow the existing code style and linting rules.
- Documentation: Update or add documentation as necessary.
- Testing: Include tests for new features or bug fixes.
- Commit Messages: Use clear and descriptive commit messages.
For more details, refer to the CONTRIBUTING.md file.
This project is licensed under the MIT License. You are free to use, modify, and distribute this software in accordance with the license terms.
For any inquiries or support, please open an issue on the GitHub repository.
- OpenAI for providing the Swarm API.
- Lodash for utility functions.
- date-fns for date manipulation.
- dotenv for environment variable management.
- Jest for testing framework.
- ESLint for linting.
Happy Coding! 🚀