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

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/knowledge, @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
• Retrieval and embeddings for RAG, knowledge lookup, 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