@runwayml/avatars-node-rpc

Node.js handler for backend RPC tool calls in Runway avatar sessions.

This package joins a LiveKit room as a hidden participant and dispatches incoming tool call requests from the avatar worker to your handler functions via LiveKit RPC.

Installation

npm install @runwayml/avatars-node-rpc

Requires Node.js 18 or later.

Usage

With API key and session ID

The package calls the /connect_backend endpoint and joins the room automatically:

import { createRpcHandler } from '@runwayml/avatars-node-rpc';

const handler = await createRpcHandler({
  apiKey: process.env.RUNWAYML_API_SECRET!,
  sessionId: 'your-session-id',
  tools: {
    lookup_trivia: async (args) => {
      const question = await db.getRandomQuestion(args.category as string);
      return { question: question.text, options: question.choices };
    },
  },
  onConnected: () => console.log('Connected to session'),
  onDisconnected: () => console.log('Session ended'),
  onError: (err) => console.error('RPC error:', err),
});

await handler.close();

With pre-fetched credentials

If you already called /connect_backend yourself:

const handler = await createRpcHandler({
  credentials: {
    url: 'wss://livekit.example.com',
    token: '<jwt>',
    roomName: '<session-id>',
  },
  tools: {
    lookup_trivia: async (args) => {
      return { answer: 'The mitochondria is the powerhouse of the cell' };
    },
  },
});

API

createRpcHandler(options): Promise<RpcHandler>

Connects to a LiveKit room and starts handling tool call requests.

Options:

Option	Type	Description
apiKey	string	Runway API key. Required if credentials is not provided.
sessionId	string	Session ID. Required if credentials is not provided.
baseUrl	string	Base URL for the Runway API. Defaults to https://api.dev.runwayml.com.
credentials	{ url, token, roomName }	Pre-fetched LiveKit credentials. Alternative to apiKey + sessionId.
tools	Record<string, ToolHandler>	Tool handler functions keyed by tool name.
onConnected	() => void	Called when connected to the LiveKit room.
onDisconnected	() => void	Called when disconnected.
onError	(error: Error) => void	Called on handler errors.
debug	boolean	Log RPC method calls for debugging.

ToolHandler: (args: Record<string, unknown>) => Promise<Record<string, unknown>>

Each tool handler receives the arguments from the LLM and returns a result object. If a handler throws, the error message is sent back to the worker so it doesn't hang until timeout.

RpcHandler

Property/Method	Type	Description
close()	Promise<void>	Disconnect from the room and clean up.
connected	boolean	Whether currently connected to the room.

License

MIT