Basic Usage

A Workflow in LlamaIndex.TS is an event-driven abstraction used to chain together several events. Workflows are made up of steps, with each step responsible for handling certain event types and emitting new events.

Workflows are designed for any cases that benefit from event-driven programming, not only for LLM and AI tasks.

npm install @llamaindex/workflow

Start from scratch

Let's start from a Hello World workflow.

const contextData: ContextData = { counter: 0 };
 
const 
const workflow: Workflow<ContextData, string, string>workflow = new Workflow<ContextData, string, string>();

First, we define a workflow with 3 generic types: ContextData, Input, and Output.

In general, ContextData is used to store the shared data between steps, Input is the type of the input event, and Output is the type of the output event.

In you code logic, you should share state between steps via ContextData.

workflow.addStep({
	inputs: [StartEvent<string>],
	outputs: [StopEvent<string>]
}, async (context, startEvent) => {
	const input = startEvent.data;
	context.data.counter++;
	return new StopEvent(`Hello, ${input}!`);
});

In the workflow, we add a step that listens to StartEvent<string> and emits StopEvent<string>.

The step is an async function that takes two arguments: context and event.

`context` type

Prop	Type	Default
`data`	`NonNullable<Data>`	-
`sendEvent`	`(event: WorkflowEvent<unknown>) => void`	-
`requireEvent`	`<T extends AnyWorkflowEventConstructor>(event: T) => Promise<InstanceType<T>>`	-

There are two more properties in HandlerContext:

sendEvent: invoke another event in the workflow, other than StartEvent, StopEvent, or the current event. (Or there will have circular reference)
requireEvent: wait for a specific event to be emitted.

You can use sendEvent and requireEvent to build complex workflows.

class AnalysisStartEvent extends WorkflowEvent<string> {}
class AnalysisStopEvent extends WorkflowEvent<boolean> {}
workflow.addStep({
	inputs: [AnalysisStartEvent],
	outputs: [AnalysisStopEvent]
}, async (...args) => {
	// do some analysis
	return new AnalysisStopEvent(true);
})
workflow.addStep({
	inputs: [StartEvent<string>],
	outputs: [StopEvent<string>]
}, async (context, startEvent) => {
	const input = startEvent.data;
	context.sendEvent(new AnalysisStartEvent('start'));
	context.data.counter++;
	const { data } = await context.requireEvent(AnalysisStopEvent);
	return new StopEvent(`Hello, ${input}! Analysis result: ${data ? 'success' : 'fail'}`);
});

For example, you can compile requireEvent with waitUntil in Vercel Functions or Cloudflare Worker

workflow.addStep({
	inputs: [StartEvent<string>],
	outputs: [StopEvent<string>]
}, async (context, startEvent) => {
	const input = startEvent.data;
	context.sendEvent(new AnalysisStartEvent('start'));
	context.data.counter++;
	waitUntil(context.requireEvent(AnalysisStopEvent));
	// note that `waitUntil` is not a promise, it will extend the lifetime of the workflow
	// you can wait for some background tasks to finish
	return new StopEvent(`Hello, ${input}!`);
});

Multiple runs

You can run the same workflow multiple times with different inputs.

{
	const ret = await workflow.run('Alex', contextData);
	console.log(ret.data); // Hello, Alex!
}
 
{
	const ret = await workflow.run('World', contextData);
	console.log(ret.data); // Hello, World!
}

Context is shared between runs, so the counter will be increased.

Ideally, it should be serializable to make sure it can be recovered from HTTP requests or other storage.

Full example

`Workflow` type

Prop	Type	Default
`addStep`	`<const In extends [AnyWorkflowEventConstructor \| StartEventConstructor, ...(AnyWorkflowEventConstructor \| StopEventConstructor)[]], const Out extends (AnyWorkflowEventConstructor \| StopEventConstructor)[]>(parameters: StepParameters<...>, stepFn: (context: HandlerContext<...>, ...events: { [K in keyof In]: InstanceT...`	-
`hasStep`	`(stepFn: StepHandler<unknown, [AnyWorkflowEventConstructor \| StartEventConstructor<string>], []>) => boolean`	-
`removeStep`	`(stepFn: StepHandler<unknown, [AnyWorkflowEventConstructor \| StartEventConstructor<string>], []>) => Workflow<ContextData, Start, Stop>`	-
`run`	`{ (event: Start \| StartEvent<Start>): unknown extends ContextData ? WorkflowContext<Start, Stop, ContextData> : WorkflowContext<...>; <Data extends ContextData>(event: Start \| StartEvent<...>, data: Data): WorkflowContext<...>; }`	-
`recover`	`(data: ArrayBuffer) => WorkflowContext<Start, Stop, ContextData>`	-

`WorkflowContext` type

Prop	Type	Default
`strict`	`() => WorkflowContext<Start, Stop, Data>`	-
`data`	`NonNullable<Data>`	-
`with`	`<Initial extends Data>(data: Initial) => WorkflowContext<Start, Stop, Initial>`	-
`then`	`<TResult1, TResult2 = never>(onfulfilled?: ((value: StopEvent<Stop>) => TResult1 \| PromiseLike<TResult1>) \| null \| undefined, onrejected?: ((reason: unknown) => TResult2 \| PromiseLike<...>) \| null \| undefined) => Promise<...>`	-
`catch`	`<TResult = never>(onrejected?: ((reason: unknown) => TResult \| PromiseLike<TResult>) \| null \| undefined) => Promise<StopEvent<Stop> \| TResult>`	-
`finally`	`(onfinally?: (() => void) \| null \| undefined) => Promise<never>`	-
`snapshot`	`() => ArrayBuffer`	-
`__@asyncIterator@99`	`() => AsyncIterableIterator<WorkflowEvent<unknown>>`	-
`__@toStringTag@101`	`string`	-

Basic Usage

Start from scratch

context type

Multiple runs

Full example

Workflow type

WorkflowContext type

On this page

`context` type

`Workflow` type

`WorkflowContext` type