Vitrus

A TypeScript client for multi Agent-World-Actor orchestration, with easy-to-use spatial perception Workflows. For detailed documentation and more examples access Vitrus Docs.

💡 Tip: If anything takes more than 2 minutes to setup, ask in our Discord channel.

Installation

# Using npm
npm install vitrus

# Using bun
bun add vitrus

Communication

Agent–actor traffic (commands, responses, broadcasts, events) uses Websockets as the core transport. The client connects to AI agents over WebSocket once for handshake (API key, world ID).

Authentication

Get an API Key

import Vitrus from "vitrus";

// Initialize the client with all options
const vitrus = new Vitrus({
  apiKey: process.env["VITRUS_API_KEY"],
});

Workflows

// running a basic workflow
const result = await vitrus.workflow("hello-world", {
  prompt: "hello world!",
});

console.log(result);

Workflows are processed in server-side GPUs (e.g. Nvidia A100), and are custom per server.

Available Workflows

We are continously updating the available workflows, and keeping them up to date with state-of-the-art (SOTA) AI models. For the latest list of workflows, you can execute:

const workflows = vitrus.list_workflows();
console.log(workflows);

Worlds and Actors

Create a world at app.vitrus.ai.

import Vitrus from "vitrus";

// Initialize the client
const vitrus = new Vitrus({
  apiKey: "your-api-key",
 // baseUrl: "ws://<dao-server>:<port>" defines an alternate server
});

Actors actions

import Vitrus from "vitrus";

const vitrus = new Vitrus({
  apiKey: "<your-api-key>",
  world: "<selected-world-id>",
});

const actor = await vitrus.actor("forest", {
  droid: "r2d2",
  weapon: "that little electric thing!",
  purpose: `find Luke to give him the princess' hologram message about the death star` 
});

actor.on("walk", (args: any) => {
  console.log("received", args);
  return "I roll";
});

actor.broadcast("status" , { alive: true });

Agents

On the Agent side, once connected to, the actor can be treated as "functions".

import Vitrus from "vitrus";

const vitrus = new Vitrus({
  apiKey: "<your-api-key>",
  world: "<world-id>", //must match actor's world
});

const actor = await vitrus.actor("forest");

const resp = await actor.run("walk", {
  direction: "front",
});

Actor → Agent events

Ad-hoc events let an actor notify agents about local state changes.

// actor side
actor.event("voice_activity", { data: true });

// agent side
actor.listen("voice_activity", (args) => {
  console.log("voice activity:", args);
});

How Vitrus works internally

Vitrus workflows, worlds, actors and agents runs on top of Distributed Actor Orchestration (DAO). A lightweight cloud system that enables the cross-communication of agents-world-actors.