Skip to main content

RunGraphOptions

Description​

RunGraphOptions configures a graph run. The base type comes from @valerypopoff/rivet2-core; @valerypopoff/rivet2-node extends it with Node remote-debugger fields.

Use this type when calling runGraph, runGraphInFile, or createProcessor.

Definition​

type RunGraphOptions = {
  graph?: string;
  inputs?: Record<string, LooseDataValue>;
  context?: Record<string, LooseDataValue>;
  nativeApi?: NativeApi;
  datasetProvider?: DatasetProvider;
  audioProvider?: AudioProvider;
  mcpProvider?: MCPProvider;
  externalFunctions?: {
    [key: string]: ExternalFunction;
  };
  onUserEvent?: {
    [key: string]: (data: DataValue | undefined) => void;
  };
  abortSignal?: AbortSignal;
  registry?: NodeRegistration<any, any>;
  includeTrace?: boolean;
  concurrency?: GraphProcessorConcurrency;
  getChatNodeEndpoint?: ProcessContext['getChatNodeEndpoint'];
  tokenizer?: Tokenizer;
  codeRunner?: ProcessContext['codeRunner'];
  projectPath?: string;
  projectReferenceLoader?: ProjectReferenceLoader;
  editorExecutionCache?: ProcessContext['editorExecutionCache'];
} & {
  [P in keyof ProcessEvents as `on${PascalCase<P>}`]?: (params: ProcessEvents[P]) => void;
} & Settings;

type NodeRunGraphOptions = RunGraphOptions & {
  remoteDebugger?: RivetDebuggerServer;
  remoteDebuggerRequestId?: RemoteRunRequestId;
};

Properties​

graph​

Type: string

The graph to execute. This may be the graph ID or the graph name shown in Rivet. If omitted, Rivet runs project.metadata.mainGraphId.

inputs​

Type: Record<string, LooseDataValue>

Input values for Graph Input nodes in the graph. Object keys must match Graph Input IDs.

See LooseDataValue for more information about the different types of values that can be passed to the graph.

context​

Type: Record<string, LooseDataValue>

Context values for Context nodes. Context is similar to inputs, but the values are available to every graph and subgraph in the run.

See LooseDataValue for more information about the different types of values that can be passed to the graph.

nativeApi​

Type: NativeApi

Provides file-system and other native capabilities for nodes that require host APIs. The Node package supplies NodeNativeApi by default.

datasetProvider​

Type: DatasetProvider

Provides dataset storage for dataset nodes.

audioProvider​

Type: AudioProvider

Provides audio loading/processing capabilities when a run needs them.

mcpProvider​

Type: MCPProvider

Provides MCP server discovery and tool/prompt calls for MCP nodes. The Node package supplies NodeMCPProvider by default.

externalFunctions​

Type: { [key: string]: ExternalFunction }

External functions that can be invoked by External Call nodes. Each key is the function name exposed to the graph.

A function must return a Promise that resolves to a DataValue or undefined. The DataValue returned by the function will be passed to the graph as the result of the function call.

See DataValue for more information about the different types of values that can be returned from an external function.

onUserEvent​

Type: { [key: string]: (data: DataValue | undefined) => void }

User event handlers. The keys are event names and the values are callbacks invoked when a Raise Event node or compatible graph event emits that user event.

abortSignal​

Type: AbortSignal

The abortSignal property is an optional AbortSignal instance. This can be used to send an abort signal to the graph processing operation, allowing you to programmatically stop the execution process.

registry​

Type: NodeRegistration

Overrides the node registry used for the run. Use this when running with custom plugin nodes or a preassembled registry.

includeTrace​

Type: boolean

Includes trace events in graph processing.

concurrency​

Type: GraphProcessorConcurrency

Controls graph processor concurrency, including the default concurrency used by node run modes that process many items in parallel.

getChatNodeEndpoint​

Type: ProcessContext['getChatNodeEndpoint']

Overrides the legacy Chat node endpoint resolver.

tokenizer​

Type: Tokenizer

Overrides the tokenizer used by token-counting nodes and chat-message trimming. Core runs use GptTokenizerTokenizer by default. Node runs use a lightweight fallback tokenizer unless you provide one.

codeRunner​

Type: ProcessContext['codeRunner']

Overrides the Code node runner. Node integrations use NodeCodeRunner by default.

projectPath​

Type: string

Provides the current project path to nodes and project-reference loaders. This is important for file-relative behavior and project references.

projectReferenceLoader​

Type: ProjectReferenceLoader

Overrides project reference loading for project-reference scenarios. The Node package supplies NodeProjectReferenceLoader by default.

editorExecutionCache​

Type: ProcessContext['editorExecutionCache']

Passes the editor execution cache used by app/editor runs.

remoteDebugger​

Type: RivetDebuggerServer

Node-only. Passes a debugger server instance so graph execution can be inspected in the Rivet app's remote debugger.

remoteDebuggerRequestId​

Type: RemoteRunRequestId

Node-only. Associates a run with a specific remote-debugger request.

Event Handlers​

Type:

{
  [P in keyof ProcessEvents as `on${PascalCase<P>}`]?: (params: ProcessEvents[P]) => void;
}

Graph processor event handlers. Event names are PascalCase and prefixed with on, such as onStart, onNodeStart, onNodeFinish, onNodeError, onPartialOutput, and onDone.

Settings​

The optional properties of Settings are merged into RunGraphOptions. Node runs fill unset OpenAI/plugin environment defaults from process.env where possible.

Node Package Defaults​

When using @valerypopoff/rivet2-node, createProcessor and runGraph provide these defaults when the corresponding option is omitted:

OptionNode default
nativeApiNodeNativeApi
mcpProviderNodeMCPProvider
tokenizerfallback character-count tokenizer
codeRunnerNodeCodeRunner
projectReferenceLoaderNodeProjectReferenceLoader
pluginEnvplugin environment values read from process.env
OpenAI settingsOPENAI_API_KEY, OPENAI_ORG_ID, and OPENAI_ENDPOINT when unset

Usage​

import { loadProjectFromFile, runGraph } from '@valerypopoff/rivet2-node';

const project = await loadProjectFromFile('./workflow.rivet-project');

const outputs = await runGraph(project, {
  graph: 'Main',
  inputs: {
    prompt: 'Summarize the release notes',
    maxBullets: 5,
  },
  context: {
    audience: 'support team',
  },
  onNodeError({ node, error }) {
    console.error(`Node failed: ${node.title}`, error);
  },
});

See Also​