NeMo Relay

nemo-relay-node is the NeMo Relay package for Node.js applications. It gives JavaScript and TypeScript code access to the same execution scopes, middleware, plugins, lifecycle events, and observability model used by the Rust runtime.

The package is implemented as a napi-rs native extension, but Node.js users should install it from npm rather than depend on the Rust crate directly.

Why Use It?

Use the Node.js binding for the following tasks:

• Own execution context in Node.js: Group agent, tool, and LLM work into one scope tree from JavaScript or TypeScript.
• Put policy around callbacks: Register guardrails and intercepts for request rewriting, blocking, sanitization, and execution wrapping.
• Emit one lifecycle stream: Send runtime events to in-process subscribers, Agent Trajectory Interchange Format (ATIF), or typed OpenTelemetry workflows.
• Use package entry points by need: Import the main runtime surface plus typed, plugin, adaptive, and observability helpers from npm.

What You Get

The Node.js package provides the following capabilities:

• npm package for Node.js: A Node.js 24 or newer package backed by a napi-rs native extension.
• Managed tool and LLM execution: Helpers that emit lifecycle events and run middleware in a consistent order.
• Middleware APIs: Guardrails and intercepts for tool and LLM boundaries, plus mark and scope event sanitizers for data, categoryProfile, and metadata.
• Observability exporters: OpenTelemetrySubscriber accepts one required full, gen_ai, or openinference endpoint configuration. The nemo-relay-node/observability helper configures plugin-owned endpoint fan-out.
• Additional entry points: nemo-relay-node/typed, nemo-relay-node/plugin, nemo-relay-node/adaptive, and nemo-relay-node/observability.

Installation

Install the npm package in a Node.js 24 or newer project:

npm install [email protected]

Getting Started

Register a subscriber and emit a mark inside a scope:

const {
  ScopeType,
  deregisterSubscriber,
  event,
  flushSubscribers,
  registerSubscriber,
  withScope,
} = require("nemo-relay-node");

async function main() {
  registerSubscriber("printer", (runtimeEvent) => {
    console.log(`${runtimeEvent.kind} ${runtimeEvent.name}`);
    console.log(JSON.stringify(runtimeEvent));
  });

  await withScope("demo-agent", ScopeType.Agent, async (handle) => {
    event("initialized", handle, { binding: "node" }, null);
  });

  await flushSubscribers();
  deregisterSubscriber("printer");
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Native subscriber delivery is asynchronous. Awaiting flushSubscribers() drains the native dispatcher and waits for managed terminal publications registered before the call and the JavaScript subscriber callbacks they queue, without blocking the Node.js event loop. Native events emitted by a JavaScript subscriber are separate publications; flush again if those events must also be observed. Subscribers can return Promise objects. A synchronous throw or a rejected Promise from a subscriber is isolated: it does not terminate the host or reject flushSubscribers(), and Relay reports the failure to stderr and through getLastCallbackError().

The main runtime API is exported from nemo-relay-node. Additional entry points are available at nemo-relay-node/typed, nemo-relay-node/plugin, nemo-relay-node/adaptive, and nemo-relay-node/observability.

Documentation

NeMo Relay Documentation: https://docs.nvidia.com/nemo/relay