Graphs

In the Inworld Agent Runtime, a graph is the core orchestration unit. Graphs contain nodes connected by edges, and manage the execution flow of data through the entire system.

Overview

There are two primary steps in setting up your experience using Inworld Graphs:

Graph Creation: Creating a graph, adding nodes, connecting them with edges, defining start/end points, and building the graph
Graph Execution: Process your data by providing input to the graph and capturing the results from your target nodes

The following sections provide more details about each step.

Graph Creation

Basic Graph

The simplest form of a graph is a single node graph that consists of:

creating a node
creating a graph builder
adding the node to the graph
defining that node as the start and end points for execution
building the graph

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

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

// Create and configure the graph
const graph = new GraphBuilder({
  id: 'MyBasicGraph',
  apiKey: process.env.INWORLD_API_KEY,
  enableRemoteConfig: false,
})
  .addNode(llmNode)
  .setStartNode(llmNode)
  .setEndNode(llmNode)
  .build();

Multi-Node Graph

Most graphs will consist of multiple nodes that can power more advanced functionality. The below example shows how to create a graph that outputs the LLM response as audio, using TTS.

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

// Create multiple nodes
const llmNode = new RemoteLLMChatNode({
  id: 'llm_node',
  provider: 'openai',
  modelName: 'gpt-4o-mini',
  stream: false,
});

const textChunkingNode = new TextChunkingNode({
  id: 'text_chunking_node',
});

const ttsNode = new RemoteTTSNode({
  id: 'tts_node',
  speakerId: 'Dennis',
  modelId: 'inworld-tts-2',
  sampleRate: 24000,
  temperature: 0.7,
  speakingRate: 1.0,
});

// Build the graph with multiple nodes and edges
const graph = new GraphBuilder({ id: 'llm-tts-graph', apiKey: process.env.INWORLD_API_KEY, enableRemoteConfig: false })
  .addNode(llmNode)
  .addNode(textChunkingNode) 
  .addNode(ttsNode)
  .addEdge(llmNode, textChunkingNode)
  .addEdge(textChunkingNode, ttsNode)
  .setStartNode(llmNode)
  .setEndNode(ttsNode)
  .build();

Graph with Multiple Start Nodes

Graphs require at least one start node and end node, but they can also have multiple start or end nodes. You can define this with setStartNodes() and setEndNodes().

import 'dotenv/config';

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

// Custom node that combines both LLM outputs
class CombineColorsNode extends CustomNode {
    process(context: ProcessContext, color1: GraphTypes.Content, color2: GraphTypes.Content): GraphTypes.Content {
        const output = `LLM 1 favorite color: ${color1.content}, LLM 2 favorite color: ${color2.content}`;
        console.log('\n' + output + '\n');
        return new GraphTypes.Content({ content: output });
    }
}

// Create LLM nodes and print node
const llm1 = new RemoteLLMChatNode({
    id: 'llm-1',
    modelName: 'gpt-4.1-nano',
    provider: 'openai'
});

const llm2 = new RemoteLLMChatNode({
    id: 'llm-2',
    modelName: 'gemini-2.0-flash',
    provider: 'google'
});

const combineNode = new CombineColorsNode({ id: 'combine-colors' });

// Build graph with two start nodes
const graphBuilder = new GraphBuilder({
  id: 'two-start-nodes-example',
  apiKey: process.env.INWORLD_API_KEY,
  enableRemoteConfig: false
})
  .addNode(llm1)
  .addNode(llm2)
  .addNode(combineNode)
  .addEdge(llm1, combineNode)
  .addEdge(llm2, combineNode)
  .setStartNodes([llm1, llm2])
  .setEndNodes([combineNode]);

const executor = graphBuilder.build();

// Execute the graph
async function main() {
  const input = new GraphTypes.LLMChatRequest({
    messages: [{
      role: 'user',
      content: 'What is your favorite color? Return just the color'
    }]
  });

  const { outputStream } = await executor.start(input);
  for await (const event of outputStream) {
    await event.processResponse({
      Content: (data: GraphTypes.Content) => {}
    });
  }
}

main();

Graph Datastore

The datastore is a key-value storage mechanism that allows you to pass additional data across nodes in a graph execution. You can access the datastore through ProcessContext in any custom node’s process() method, and use add() to store data and get() to retrieve it. See this guide on using context for an example of how to use the datastore.

Graph Execution

After a graph has been created, it needs to be executed by providing input data and handling the results. The execution returns a stream that allows you to process the output from the graph.

v0.8 Breaking Change: graph.start() is now async and must be awaited. Additionally, you should call stopInworldRuntime() for proper cleanup when your application terminates.

Below is an example of executing the graph we created above.

import { GraphTypes } from '@inworld/runtime/graph';
import { stopInworldRuntime } from '@inworld/runtime';

async function main() {
  // Execute the graph (now requires await)
  const { outputStream } = await graph.start(new GraphTypes.LLMChatRequest({
    messages: [{ role: 'user', content: 'Hello, how are you?' }]
  }));

  // Handle response
  for await (const result of outputStream) {
    await result.processResponse({
      Content: (response) => console.log('Response:', response.content),
      TTSOutputStream: async (ttsStream) => {
        for await (const chunk of ttsStream) {
          console.log('Audio chunk received');
        }
      },
    });
  }

  // Cleanup (required for proper resource management)
  await stopInworldRuntime();
}

main();

Execution Result

The start() method returns an ExecutionResult object with the following properties:

const { variantName, outputStream, executionId } = await graph.start(input);

variantName - The variant of the graph that was executed (default: "__default__")
outputStream - The output stream for processing results
executionId - Unique identifier for this execution

Get Started

Build with Agent Runtime

Deploy

Monitor & Experiment

Inworld CLI

SDK Reference

Resources

Overview

Graph Creation

Basic Graph

Multi-Node Graph

Graph with Multiple Start Nodes

Graph Datastore

Graph Execution

Execution Result

​Overview

​Graph Creation

​Basic Graph

​Multi-Node Graph

​Graph with Multiple Start Nodes

​Graph Datastore

​Graph Execution

​Execution Result

Overview

Graph Creation

Basic Graph

Multi-Node Graph

Graph with Multiple Start Nodes

Graph Datastore

Graph Execution

Execution Result