Nodes

Inworld offers a number of different Built-in Nodes that can be used to build a Graph. In addition to provided Built-in Nodes, you can also create your own node using Custom Nodes.

To use a node in a graph:

Create the node: Instantiate the node with configuration options.
Add node to graph: Add the node to the graph.

import { GraphBuilder, RemoteLLMChatNode } from '@inworld/runtime/graph';

// Create an LLM node
const llmNode = new RemoteLLMChatNode({
  id: 'llm_node',
  provider: 'openai',
  modelName: 'gpt-4o-mini',
  stream: true,
});

// Build graph
const graph = new GraphBuilder({
  id: 'my-graph',
  apiKey: process.env.INWORLD_API_KEY,
  enableRemoteConfig: false,
})
  .addNode(llmNode)
  .setStartNode(llmNode)
  .setEndNode(llmNode)
  .build();

Node configurations

Nodes are created with various configuration options that control their behavior. Different nodes types will have different node-specific configurations, but all nodes will include the following optional configurations:

id: Unique identifier for the node (auto-generated if not provided)
reportToClient: Defaults to false, which means the node’s result will be passed to the next nodes in the graph, but will not be available to the client. If true, the node’s result will be sent to the client immediately when available AND propagated to the next nodes. This is useful if you want to access the intermediate node result (e.g., to display in the UI).

Below is an example of configuring an LLM node, where provider and modelName are LLM node specific parameters:

Node

const llmNode = new RemoteLLMChatNode({
  id: 'my_llm_node',
  reportToClient: true,
  provider: 'openai',
  modelName: 'gpt-4o-mini',
});

See the Node.js Runtime Reference for the configurations available for each node.

Additional error handling configurations coming soon!

Built-in Nodes

Built-in nodes are pre-built nodes provided by Inworld that cover common use cases. Below is an overview of available Built-in Nodes.

Nodes with an asterisk (*) are experimental and subject to change.

Node	Description	Input Type(s)	Output Type(s)
KeywordMatcherNode	Matches keywords in text input	String	GraphTypes.MatchedKeywords
KnowledgeNode*	Retrieves relevant knowledge based on input text	String	GraphTypes.KnowledgeRecords
LLMChatRequestBuilderNode	Generates formatted chat requests using prompt templates populated with JSON input	Object	GraphTypes.LLMChatRequest
LLMPromptBuilderNode	Generates formatted prompts using prompt templates populated with JSON input	Object	String
MCPCallToolNode	Calls multiple tools on an MCP server in parallel	GraphTypes.ToolCallRequest	GraphTypes.ToolCallResponse
MCPListToolsNode	Lists available tools from an MCP server	any	GraphTypes.ListToolsResponse
ProxyNode	Simple data passing node for forwarding input to output	any	any
RandomCannedTextNode	Selects a random text from a list of predefined phrases	any	String
RemoteLLMChatNode	Generates a response using a large language model	GraphTypes.LLMChatRequest	GraphTypes.LLMChatResponse
RemoteLLMCompletionNode	Generates text completion using a large language model	String	String
RemoteSTTNode	Converts speech audio to text using a speech-to-text (STT) model	GraphTypes.Audio	String
RemoteTTSNode	Converts text-to-speech audio using a text-to-speech (TTS) model	String GraphTypes.TextStream GraphTypes.TTSRequest	GraphTypes.TTSOutputStream
SafetyCheckerNode	Analyzes text for potentially harmful content and returns safety assessment results	String	GraphTypes.SafetyResult
SubgraphNode	Executes a compiled subgraph as a node	any	any
TextAggregatorNode	Combines text streams (chunks) into a single string	String GraphTypes.TextStream GraphTypes.LLMChatResponse	String
TextChunkingNode	Splits text into smaller chunks	GraphTypes.TextStream GraphTypes.ContentStream	GraphTypes.TextStream
TextClassifierNode	Analyzes text and classifies it into predefined categories using ML models	String	GraphTypes.ClassificationResult

Subgraphs

Use subgraphs to simplify maintenance, improve readability, and promote reusability

The SubgraphNode is a special type of node that executes a compiled Subgraph. A Subgraph is a reusable graph component that encapsulate a set of nodes and edges into a single logical unit. To use a subgraph in your main graph, you need to:

Build the subgraph using SubgraphBuilder, which follows a very similar syntax as GraphBuilder. This includes adding nodes, adding edges, and setting the start and end node. A Subgraph must have exactly one start node and one end node.
Create a SubgraphNode that references the subgraph by its ID
Register the subgraph with your main graph using .addSubgraph()
Add the SubgraphNode to your main graph like any other node

In the example below, the text processing subgraph handles chunking and aggregating text, while the main graph orchestrates the overall flow using proxy nodes for input and output handling.

import { 
  GraphBuilder, 
  SubgraphBuilder, 
  SubgraphNode,
  TextChunkingNode,
  TextAggregatorNode,
  ProxyNode 
} from '@inworld/runtime/graph';

const textChunkingNode = new TextChunkingNode({ reportToClient: true });
const textAggregatorNode = new TextAggregatorNode();

// Create a reusable text processing subgraph
const textProcessingSubgraph = new SubgraphBuilder('text_processing_subgraph')
  .addNode(textChunkingNode)
  .addNode(textAggregatorNode)
  .addEdge(textChunkingNode, textAggregatorNode)
  .setStartNode(textChunkingNode)
  .setEndNode(textAggregatorNode);

// Create a SubgraphNode
const subgraphNode = new SubgraphNode({
  subgraphId: 'text_processing_subgraph',
});

const inputProxy = new ProxyNode();
const outputProxy = new ProxyNode();

const graph = new GraphBuilder({
  id: 'main_graph',
  enableRemoteConfig: false,
})
  .addSubgraph(textProcessingSubgraph) // Register the subgraph
  .addNode(inputProxy)
  .addNode(subgraphNode)               // Add the SubgraphNode
  .addNode(outputProxy)
  .addEdge(inputProxy, subgraphNode)
  .addEdge(subgraphNode, outputProxy)
  .setStartNode(inputProxy)
  .setEndNode(outputProxy)
  .build();

Custom Nodes

Custom Nodes can be created to implement any custom logic in your graph by extending the CustomNode class. To use a custom node:

Create a custom node class: Extend CustomNode and implement the process method with your custom logic.
Instantiate the custom node: Create an instance of your custom node class.
Add custom node to graph: Use addNode to add the custom node to the graph.

The below example creates a custom node that reverses a string.

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

// Create a custom node class
class ReverseTextNode extends CustomNode {
  process(context: ProcessContext, input: string): string {
    return input.split('').reverse().join('');
  }
}

// Create the custom node instance
const customNode = new ReverseTextNode();

// Add it to the graph, same as a built-in node
const graph = new GraphBuilder({
  id: 'custom-graph',
  apiKey: process.env.INWORLD_API_KEY,
  enableRemoteConfig: false,
})
  .addNode(customNode)
  .setStartNode(customNode)
  .setEndNode(customNode)
  .build();

Custom nodes can also be useful for processing inputs from multiple nodes, as shown in this guide.

​Nodes

​Node configurations

​Built-in Nodes

​Subgraphs

​Custom Nodes

Nodes

Node configurations

Built-in Nodes

Subgraphs

Custom Nodes