llamaindex

Understanding @llamaindex/workflow-core (TypeScript)

This document explains the core concepts of the @llamaindex/workflow-core library for TypeScript, which is used by typescript-compiler.ts to generate executable agent scripts. The library uses a functional, event-driven paradigm.

Core Concepts

The workflow is built by defining events and then creating handlers that listen for those events. The execution flow is determined by which events are emitted from handlers.

1. Event-Driven Flow: The entire workflow is orchestrated by events. A handler function executes when it receives an event of a type it's registered to handle. After executing its logic, the handler can emit a new event, which in turn triggers another handler.

2. Functional Approach: Instead of class-based inheritance (like in Python), the TypeScript version uses factory functions to build the workflow.

   • workflowEvent<T>(): Creates a new type of event.
   • createWorkflow(): Creates a new workflow instance.
   • workflow.handle([...events], handlerFn): Registers a function handlerFn to be called when any of the specified events are detected.

3. Asynchronous by Design: All handlers can be async and are expected to return Promises, making them suitable for I/O-bound tasks like LLM calls and tool interactions.

Key Components

1. workflowEvent

This function is used to define the different types of events that will flow through your system. They are the data carriers.

import { workflowEvent } from "@llamaindex/workflow-core";

// Define an event that carries a string payload
const startEvent = workflowEvent<string>();

// Define an event that carries a structured object
interface ToolCall {
  id: string;
  name: string;
  args: any;
}
const toolCallEvent = workflowEvent<ToolCall>();

2. createWorkflow and .handle

createWorkflow() creates the main workflow object. The .handle() method is then used to register listeners for specific events. The return value of a handler function becomes a new event that is dispatched into the workflow.