Inworld Node.js Runtime SDK

@inworld/runtime is a Node.js SDK for building AI applications with LLM inference, graph orchestration, speech pipelines, retrieval, tool use, and telemetry.

Read the documentation to explore the full platform.

Requirements

• Node.js 20 or newer

Installation

npm install @inworld/runtime

On supported environments, the package completes native runtime setup during installation.

Quickstart Example

The example below builds and runs a one-node graph locally. It is the simplest way to understand the @inworld/runtime/graph execution model, and it does not require an API key.

import { stopInworldRuntime } from '@inworld/runtime';
import {
  CustomNode,
  GraphBuilder,
  ProcessContext,
} from '@inworld/runtime/graph';

class ReverseTextNode extends CustomNode {
  process(_context: ProcessContext, input: string): string {
    return input.split('').reverse().join('');
  }
}

async function main() {
  const node = new ReverseTextNode();

  const graph = new GraphBuilder({
    id: 'custom_reverse_graph',
    enableRemoteConfig: false,
  })
    .addNode(node)
    .setStartNode(node)
    .setEndNode(node)
    .build();

  const { outputStream } = await graph.start('Hello, Inworld!');
  const result = await outputStream.next();

  await result.processResponse({
    string: (text) => console.log(text),
    default: (value) => console.log(value),
  });
}

main()
  .catch(console.error)
  .finally(async () => {
    await stopInworldRuntime();
  });

Authentication

For remote services such as hosted LLM, STT, and TTS, set your Base64-encoded Runtime API key before running examples. See the authentication guide for details on getting a key.

In the examples below, INWORLD_API_KEY is used as the default credential source for hosted requests. If you pass credentials in request options, those request-level credentials override the default env-backed credentials for that call.

export INWORLD_API_KEY="<your-base64-runtime-api-key>"

Optional advanced environment variables:

• INWORLD_ADDON_POOL_SIZE: Tunes native addon concurrency for high-throughput workloads

Inworld Runtime CLI (inworld-runtime)

Installing @inworld/runtime puts an inworld-runtime command on your PATH. It scaffolds graph projects, runs and serves them locally, deploys to Inworld Cloud, and manages graph variants — the same surface previously shipped as @inworld/cli's graph commands.

Install and verify

# Global install gives you `inworld-runtime` everywhere
npm install -g @inworld/runtime
inworld-runtime --help

# Or use it through a project install via npx
npm install --save-dev @inworld/runtime
npx inworld-runtime --help

Authenticate and pick a workspace

inworld-runtime auth login              # browser-based OAuth, stores tokens in OS keychain
inworld-runtime auth status             # show current account, workspace, API key
inworld-runtime workspace select        # pick a workspace for subsequent commands
inworld-runtime workspace select-key    # pick an API key in the active workspace
inworld-runtime workspace add-key --write   # create a new read/write API key

CI / non-interactive flow:

inworld-runtime auth login-ci --token <firebase-token> --email <ci-account-email>
inworld-runtime auth print-api-key      # emits the API key (consumed by deployed graphs)
inworld-runtime auth print-access-token # emits a fresh access token (auto-refreshes)

Auth honours INWORLD_ENV (DEV | STAGE | PROD, defaults to PROD) and stores credentials via the OS keychain (with an encrypted-file fallback for headless environments).

Build, run, and deploy graphs

# Scaffold a new graph project from one of the official templates
inworld-runtime graph init --list-templates
inworld-runtime graph init --name my-agent --template <template-id>   # interactive without flags

# Inside your graph project
inworld-runtime graph run ./graph.ts '{"input":"hello","executionId":"00000000-0000-0000-0000-000000000000"}'
inworld-runtime graph serve ./graph.ts --port 3000               # local HTTP server (default :3000)
inworld-runtime graph serve ./graph.ts --transport grpc          # local gRPC server
inworld-runtime graph serve ./graph.ts --swagger                 # HTTP server + Swagger UI at /docs
inworld-runtime graph visualize ./graph.ts                       # render graph topology

# Deploy to Inworld Cloud (preview)
inworld-runtime graph deploy ./graph.ts                 # bundles + uploads
inworld-runtime graph deploy ./graph.ts --info          # inspect deployment plan
inworld-runtime graph deploy ./graph.ts --package-only  # produce zip without uploading

A graph file is a TypeScript / JavaScript module that exports a graph object built with GraphBuilder from @inworld/runtime/graph. The graphId must be alphanumeric, dashes, or underscores.

Manage graph variants

inworld-runtime graph variant list ./graph.ts
inworld-runtime graph variant register ./graph.ts --display-name "prod"
inworld-runtime graph variant print ./graph.ts --display-name "prod"

TTS

inworld-runtime tts list-voices --filter "language=en"
inworld-runtime tts synthesize "Hello, world" --voice <voice-id> --output ./hello.wav
inworld-runtime tts synthesize "Hello, world" --play           # synthesize + play locally
inworld-runtime tts design "warm narrator, mid-30s, female"    # interactive voice design wizard
inworld-runtime tts clone ./sample.wav --name "studio voice"   # clone from a 5-15s sample

Run any subcommand with --help for the full flag list (e.g. inworld-runtime graph deploy --help).

Direct LLM Primitive Example

If you want to call a hosted model directly, use the LLM primitive:

import { stopInworldRuntime } from '@inworld/runtime';
import { LLM } from '@inworld/runtime/primitives/llm';

async function main() {
  const llm = await LLM.create({
    remoteConfig: {
      modelId: 'openai/gpt-4o-mini',
      apiKey: process.env.INWORLD_API_KEY!,
      defaultTimeout: '30s',
      defaultConfig: {
        temperature: 0.7,
        maxNewTokens: 100,
      },
    },
  });

  const response = await llm.generateContentComplete({
    prompt: 'Write a one-sentence welcome to the Inworld Runtime SDK.',
    // Use request-level config when this call needs behavior that differs
    // from the default settings configured when the LLM instance was created.
    config: {
      temperature: 0.6,
      maxNewTokens: 80,
    },
    // Use request-level credentials when this specific call should override
    // the default credentials for the LLM instance, including values that
    // came from environment variables such as INWORLD_API_KEY.
    credentials: {
      inworldApiKey: '<request-scoped-api-key>',
    },
  });

  console.log(response);
}

main()
  .catch(console.error)
  .finally(async () => {
    await stopInworldRuntime();
  });

Choose Your Entry Point

• @inworld/runtime: Top-level runtime helpers such as stopInworldRuntime()
• @inworld/runtime/primitives/<primitive>: Direct access to specific primitive subpaths such as @inworld/runtime/primitives/llm, @inworld/runtime/primitives/speech, @inworld/runtime/primitives/mcp, @inworld/runtime/primitives/embeddings, @inworld/runtime/primitives/nlu, and @inworld/runtime/primitives/platform
• @inworld/runtime/graph: Build orchestrated pipelines with routing, reusable nodes, and realtime agent flows
• @inworld/runtime/telemetry: Add logging, tracing, and metrics to your runtime workloads

Feature Overview

• LLM generation for completion, chat, streaming, tool use, and routing
• Graph-based orchestration for multi-step AI workflows
• Speech primitives for STT, streaming STT, TTS, VAD, and turn detection
• Embeddings for semantic search and intent-driven flows
• MCP integration for external tool discovery and invocation
• Safety, goals, and observability patterns for production agents

Templates and Additional Resources

• Templates overview for runnable examples across LLM, voice, retrieval, MCP, safety, streaming, and goals
• Quickstart Guide for a guided first project
• Runtime Overview for core concepts and architecture
• Runtime Reference for API details
• Voice Agent example for a fuller end-to-end application

Troubleshooting

• Verify INWORLD_API_KEY is set when using remote services and that it uses your Base64-encoded Runtime API key
• Use Node.js 20 or newer when installing and running the package
• If installation fails, retry in a supported environment with a clean reinstall of @inworld/runtime
• Call stopInworldRuntime() when your script exits to clean up runtime resources