⌨︎ DIY

Running Swarm.js

Start by creating a Swarm client that interacts with OpenAI’s API.

Copy

Copy

const { Swarm } = require('openai-swarm-node');

const client = new Swarm(process.env.OPENAI_API_KEY);

client.run()

The 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.

Arguments

ArgumentTypeDescriptionDefault

agent

Agent

The (initial) agent to be called.

(required)

messages

Array

A list of message objects, similar to Chat Completions API messages.

(required)

contextVariables

Object

Additional context variables available to agents.

{}

maxTurns

Number

Maximum number of conversational turns before returning.

Infinity

debug

Boolean

Enables debug logging if true.

false

Response Fields

FieldTypeDescription

messages

Array

The list of messages generated during the conversation.

agent

Agent

The last agent to handle the conversation.

contextVariables

Object

The most up-to-date context variables, including any changes during the conversation.

Agents

An Agent encapsulates instructions and functions (tools). These agents drive the conversation and can decide whether to hand off to another agent.

Copy

Copy

const agentA = new Agent({
  name: "Agent A",
  instructions: "You are a helpful agent.",
});

Functions

Functions 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.

Copy

Copy

const transferToAgentB = () => agentB;

const agentA = new Agent({
  name: "Agent A",
  instructions: "You are a helpful agent.",
  tools: [{ name: 'transferToAgentB', fn: transferToAgentB }],
});

Handoffs and Context Variables

Agents can transfer control to other agents or update contextVariables based on the conversation flow.

Copy

Copy

const salesAgent = new Agent({ name: "Sales Agent" });

const agent = new Agent({
  functions: [
    () => new Result({ agent: salesAgent, contextVariables: { department: "sales" } }),
  ],
});

Function Schemas

Swarm.js automatically converts functions into JSON schemas, allowing OpenAI’s API to call the appropriate function based on the tool name.

Copy

Copy

function lookUpItem(searchQuery) {
    /**
     * @description Use to find item ID. Search query can be a description or keywords.
     * @param {string} searchQuery - Description or keywords to search for the item.
     * @returns {string} - The found item ID.
     */

    return console.log(`Searching for item: ${searchQuery}`);
}

Streaming

You can enable streaming in Swarm.js to receive real-time responses from agents.

Copy

Copy

const stream = client.run({ agent, messages, stream: true });
for await (const chunk of stream) {
    console.log(chunk);
}

Evaluations

Swarm.js supports various evaluation methods to test and validate your multi-agent systems. You can find example evaluations in the /examples directory.

Utils

Use the run_demo_loop utility to test your agents interactively in a REPL environment.

Copy

Copy

const { run_demo_loop } = require('openai-swarm-node/utils');

run_demo_loop(agent);

---

Core Contributors

• Pulkit Garg (Node.js adaptation)

• OpenAI (original Python framework)

---

This README now emphasizes that Swarm.js is a Node.js implementation of OpenAI Swarm, while maintaining a high standard for documentation and usage clarity.