{"id":17602369,"url":"https://github.com/youseai/openai-swarm-node","last_synced_at":"2026-03-06T12:03:10.340Z","repository":{"id":258487387,"uuid":"871982247","full_name":"youseai/openai-swarm-node","owner":"youseai","description":"Swarm.js is a Node.js implementation of OpenAI’s experimental Swarm framework. This SDK allows developers to orchestrate multi-agent systems using OpenAI’s API in a lightweight and ergonomic way, while leveraging Node.js for building scalable, real-world applications.","archived":false,"fork":false,"pushed_at":"2024-10-19T17:21:21.000Z","size":16,"stargazers_count":144,"open_issues_count":2,"forks_count":20,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-01T23:02:56.758Z","etag":null,"topics":["agents","ai","chat-application","chatbot-framework","framework","llm","nodejs","npm","openai","openai-api","openai-assistants","package","swarm","typescript"],"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/youseai.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-10-13T13:39:24.000Z","updated_at":"2025-06-24T07:24:55.000Z","dependencies_parsed_at":"2024-10-22T18:39:34.326Z","dependency_job_id":null,"html_url":"https://github.com/youseai/openai-swarm-node","commit_stats":{"total_commits":6,"total_committers":2,"mean_commits":3.0,"dds":"0.16666666666666663","last_synced_commit":"342dd28d6300d2c5b32c4abdacf399387b9e373e"},"previous_names":["youseai/openai-swarm-node"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/youseai/openai-swarm-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youseai%2Fopenai-swarm-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youseai%2Fopenai-swarm-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youseai%2Fopenai-swarm-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youseai%2Fopenai-swarm-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/youseai","download_url":"https://codeload.github.com/youseai/openai-swarm-node/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youseai%2Fopenai-swarm-node/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30175908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T11:48:51.886Z","status":"ssl_error","status_checked_at":"2026-03-06T11:48:51.460Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","chat-application","chatbot-framework","framework","llm","nodejs","npm","openai","openai-api","openai-assistants","package","swarm","typescript"],"created_at":"2024-10-22T13:08:01.496Z","updated_at":"2026-03-06T12:03:10.321Z","avatar_url":"https://github.com/youseai.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swarm.js (Node.js Implementation of OpenAI Swarm)\n\n**Swarm.js** is a Node.js implementation of OpenAI’s experimental Swarm framework. This SDK allows developers to orchestrate multi-agent systems using OpenAI’s API in a lightweight and ergonomic way, while leveraging Node.js for building scalable, real-world applications.\n\n\u003e **Warning**  \n\u003e Swarm.js is an experimental, educational framework designed to explore ergonomic interfaces for multi-agent systems in Node.js. It is not intended for production use and does not have official support. This framework is a Node.js adaptation of the [OpenAI Swarm](https://cookbook.openai.com/examples/orchestrating_agents) framework, which was originally designed for Python.\n\n## Install\n\nYou can install the Swarm.js SDK via npm:\n\n```bash\nnpm install openai-swarm-node\n```\n\n## What is Swarm.js?\n\nSwarm.js focuses on multi-agent **coordination** and **execution** by defining lightweight agents that can carry out tasks and hand off conversations when necessary. Inspired by OpenAI’s Python Swarm framework, this Node.js implementation allows developers to build multi-agent systems that are highly customizable, scalable, and easy to use.\n\nThe framework leverages OpenAI’s Chat Completions API and tools to create routines, handoffs, and agents that can work together in a networked fashion to solve real-world problems.\n\n\u003e **Note**  \n\u003e Swarm.js agents are powered by the Chat Completions API and are stateless between calls. They are not related to OpenAI Assistants but share a similar design philosophy in terms of agent-based interactions.\n\n## Usage\n\nSwarm.js makes it easy to define agents, assign them tasks, and manage interactions between them. Below is a simple example demonstrating how to create and orchestrate two agents.\n\n```javascript\nconst { Swarm, Agent } = require('openai-swarm-node');\n\n// Define two agents\nconst agentA = new Agent({\n    name: \"Agent A\",\n    instructions: \"You are a helpful agent.\",\n    tools: [\n        {\n            name: 'transferToAgentB',\n            fn: () =\u003e agentB,\n        },\n    ],\n});\n\nconst agentB = new Agent({\n    name: \"Agent B\",\n    instructions: \"Only speak in Haikus.\",\n});\n\nconst swarm = new Swarm(process.env.OPENAI_API_KEY);\n\n// Run conversation with agentA\n(async () =\u003e {\n    const response = await swarm.run({\n        agent: agentA,\n        messages: [{ role: \"user\", content: \"I want to talk to agent B.\" }]\n    });\n\n    console.log(response.messages.pop().content);\n})();\n```\n\n```\nHope glimmers brightly,\nNew paths converge gracefully,\nWhat can I assist?\n```\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Examples](#examples)\n- [Documentation](#documentation)\n  - [Running Swarm](#running-swarm)\n  - [Agents](#agents)\n  - [Functions](#functions)\n  - [Streaming](#streaming)\n- [Evaluations](#evaluations)\n- [Utils](#utils)\n\n## Overview\n\nSwarm.js is a Node.js implementation of OpenAI's **Swarm**, focusing on building multi-agent systems that are lightweight and easy to control. With agents that can perform tasks and hand off execution to other agents, Swarm.js enables building complex workflows using a simple set of abstractions.\n\n### Why Swarm.js?\n\nSwarm.js is an educational framework designed for developers who want to explore multi-agent orchestration in Node.js. It is inspired by OpenAI’s Swarm, which was originally designed in Python, and is perfect for situations that involve multiple independent tasks or workflows that need coordination across agents.\n\n## Examples\n\nExplore the `/examples` folder for inspiration! Each example comes with a README to explain the details of implementation.\n\n- [`basic`](examples/basic): Learn the fundamentals of agent setup, function calling, and handoffs.\n- [`triage_agent`](examples/triage_agent): A simple triage system that hands off tasks to the right agent.\n- [`airline`](examples/airline): Handle different customer service requests in the airline industry using multiple agents.\n- [`support_bot`](examples/support_bot): Build a customer service bot that handles multiple user requests using a network of agents.\n\n## Documentation\n\n### Running Swarm.js\n\nStart by creating a Swarm client that interacts with OpenAI’s API.\n\n```javascript\nconst { Swarm } = require('openai-swarm-node');\n\nconst client = new Swarm(process.env.OPENAI_API_KEY);\n```\n\n### `client.run()`\n\nThe `run()` function in Swarm.js is similar to OpenAI's `chat.completions.create()` function but with additional features like agent function execution, handoffs, context variables, and multi-turn conversations.\n\n#### Arguments\n\n| Argument              | Type    | Description                                                                                                                                            | Default        |\n| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |\n| **agent**             | `Agent` | The (initial) agent to be called.                                                                                                                      | (required)     |\n| **messages**          | `Array` | A list of message objects, similar to [Chat Completions API messages](https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages). | (required)     |\n| **contextVariables**  | `Object`| Additional context variables available to agents.                                                                                                      | `{}`           |\n| **maxTurns**          | `Number`| Maximum number of conversational turns before returning.                                                                                               | `Infinity`     |\n| **debug**             | `Boolean`| Enables debug logging if `true`.                                                                                                                       | `false`        |\n\n#### `Response` Fields\n\n| Field                 | Type    | Description                                                                                                                                             |\n| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **messages**          | `Array` | The list of messages generated during the conversation.                                                                                                  |\n| **agent**             | `Agent` | The last agent to handle the conversation.                                                                                                               |\n| **contextVariables**  | `Object`| The most up-to-date context variables, including any changes during the conversation.                                                                     |\n\n### Agents\n\nAn `Agent` encapsulates instructions and functions (tools). These agents drive the conversation and can decide whether to hand off to another agent.\n\n```javascript\nconst agentA = new Agent({\n  name: \"Agent A\",\n  instructions: \"You are a helpful agent.\",\n});\n```\n\n### Functions\n\nFunctions enable agents to perform actions like processing transactions, looking up information, or transferring control to other agents. Functions are called when the agent needs to perform a specific task.\n\n```javascript\nconst transferToAgentB = () =\u003e agentB;\n\nconst agentA = new Agent({\n  name: \"Agent A\",\n  instructions: \"You are a helpful agent.\",\n  tools: [{ name: 'transferToAgentB', fn: transferToAgentB }],\n});\n```\n\n### Handoffs and Context Variables\n\nAgents can transfer control to other agents or update `contextVariables` based on the conversation flow.\n\n```javascript\nconst salesAgent = new Agent({ name: \"Sales Agent\" });\n\nconst agent = new Agent({\n  functions: [\n    () =\u003e new Result({ agent: salesAgent, contextVariables: { department: \"sales\" } }),\n  ],\n});\n```\n\n### Function Schemas\n\nSwarm.js automatically converts functions into JSON schemas, allowing OpenAI’s API to call the appropriate function based on the tool name.\n\n```javascript\nfunction lookUpItem(searchQuery) {\n    /**\n     * @description Use to find item ID. Search query can be a description or keywords.\n     * @param {string} searchQuery - Description or keywords to search for the item.\n     * @returns {string} - The found item ID.\n     */\n\n    return console.log(`Searching for item: ${searchQuery}`);\n}\n\n```\n\n## Streaming\n\nYou can enable streaming in Swarm.js to receive real-time responses from agents.\n\n```javascript\nconst stream = client.run({ agent, messages, stream: true });\nfor await (const chunk of stream) {\n    console.log(chunk);\n}\n```\n\n## Evaluations\n\nSwarm.js supports various evaluation methods to test and validate your multi-agent systems. You can find example evaluations in the `/examples` directory.\n\n## Utils\n\nUse the `run_demo_loop` utility to test your agents interactively in a REPL environment.\n\n```javascript\nconst { run_demo_loop } = require('openai-swarm-node/utils');\n\nrun_demo_loop(agent);\n```\n\n---\n\n### Core Contributors\n\n- Pulkit Garg (Node.js adaptation)\n- OpenAI (original Python framework)\n\n---\n\nThis README now emphasizes that **Swarm.js** is a **Node.js implementation** of OpenAI Swarm, while maintaining a high standard for documentation and usage clarity.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouseai%2Fopenai-swarm-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyouseai%2Fopenai-swarm-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouseai%2Fopenai-swarm-node/lists"}