Install
npm install @llamaindex/workflow @llamaindex/openai zodEvent-driven agentic workflows in TypeScript — RAG, agent coordination, typed event handling.
Event-driven agentic workflows for TypeScript. @llamaindex/workflow models agents as typed events and handlers, with RAG primitives available from the llamaindex umbrella package.
Install
npm install @llamaindex/workflow @llamaindex/openai zodVersion
Final releases, listed below · Node 22+ · checked 2026-11-19
Best for
Maintaining existing LlamaIndex.TS code; typed event-driven flows.
No further versions will be published, so these are the versions the guides document:
| Package | Final release | Contents |
|---|---|---|
@llamaindex/workflow | 1.1.25 | Workflow runtime (createWorkflow, workflowEvent, run) and agents (agent, multiAgent), built on @llamaindex/workflow-core 1.3.x |
@llamaindex/workflow-core | 1.3.4 | The engine itself: events, handlers, stream, state and validation middleware (page) |
@llamaindex/core | 0.6.23 | LLM, tool, memory and schema interfaces |
@llamaindex/openai | 0.4.23 | OpenAI LLM and embeddings (other providers have their own package) |
llamaindex | 0.12.1 | Indexes, readers, node parsers, query and chat engines |
llamaindex 0.12.1 pins exact, slightly older versions of its dependencies: @llamaindex/workflow 1.1.24 and @llamaindex/core 0.6.22. A project that uses only workflows and agents can install the latest of each scoped package. A project that also uses llamaindex should install @llamaindex/workflow@1.1.24, so npm resolves a single copy of @llamaindex/core (and a matching @llamaindex/openai):
npm install llamaindex @llamaindex/openai @llamaindex/workflow@1.1.24 zodWith two copies installed, llamaindex prints “llamaindex was already imported”, and Settings.llm set through one copy is not seen by agents created from the other.
runWorkflow(), runAndCollect() and runStream() are marked @deprecated; use run(workflow, event).until(stopEvent).toArray() instead.handle() mutates the workflow in place and returns void — method chaining is not supported.(ctx, ...events): the first argument is the workflow context; subsequent arguments are the matched input events in order.agent(...) / multiAgent(...) expose run() (a Promise of the final stop event) and runStream() (all events).@llamaindex/workflow uses a functional API — createWorkflow, workflowEvent, run. A class-based extends Workflow + @step() pattern is the Python API and does not exist in the TypeScript package.
import { createWorkflow, workflowEvent, run } from '@llamaindex/workflow';
// Define typed events — the generic parameter is the payload typeconst startEvent = workflowEvent<{ input: string }>({ debugLabel: 'start' });const stopEvent = workflowEvent<{ result: string }>({ debugLabel: 'stop' });
// Build the workflow — handle() mutates in place; it does not return the workflowconst workflow = createWorkflow();workflow.handle([startEvent], async (ctx, start) => { return stopEvent.with({ result: `Echo: ${start.data.input}` });});
const events = await run(workflow, startEvent.with({ input: 'Hello!' })) .until(stopEvent) .toArray();console.log(events.at(-1)?.data); // { result: 'Echo: Hello!' }For runtime validation of payloads, zodEvent(schema) creates an event type from a Zod schema.
For multi-agent topologies use multiAgent(...) + FunctionAgent. For streaming use run(...).toStream() or iterate the return value of run(...) directly.
Ready? Start Zero → Hero Step 1 →
| Date | Version | Changes |
|---|---|---|
| 2026-10-24 | final releases | Added a recipe for metadata-filtered retrieval and a chat engine; the comprehensive guide named a non-existent @llamaindex/azure-openai package (the Azure classes are in @llamaindex/azure). |
| 2026-10-24 | workflow-core 1.3.4 | Added the workflows engine page for @llamaindex/workflow-core, with a working snapshot/resume example; listed the package under final releases. |
| 2026-10-21 | final releases | Final package versions now listed once, in Final releases, with the note that llamaindex pins @llamaindex/workflow 1.1.24. Corrected the claim that llamaindex re-exports the workflow API. Node 22+ (Node 20 reached end of life in April 2026). Added a real VectorStoreIndex RAG recipe; production guide rebuilt to compile under its own config. |
| 2026-10-21 | llamaindex 0.12.1 / @llamaindex/workflow 1.1.25 | Added the upstream deprecation notice (repository and npm packages deprecated). Minimal example fixed — it passed a Zod schema as workflowEvent({ data }), which is not a valid option and does not type-check. Version card now reads from the site’s version registry. Comprehensive guide, recipes and production guide re-checked with tsc. |
| 2026-05-04 | @llamaindex/workflow 1.1.25 | Bumped 1.1.24 → 1.1.25. Fixed broken minimal example: corrected handler signature to (ctx, start) (was incorrectly ({ data })); removed unsupported chaining on handle(); replaced deprecated runWorkflow() with run().until().toArray(). Added “What’s new in 1.1.25” section documenting runWorkflow deprecation and handle() void-return behaviour. Snippet executed against installed 1.1.25 in .routine-envs/check-0504-node. |
| 2026-04-21 | 1.1.24 | Minimal example rewritten against functional API (createWorkflow/workflowEvent/runWorkflow) after pkg introspection — class + @step pattern documented earlier does not exist. |
| April 2026 | 1.1.24 | Scoped package migration; typed event handlers stabilised. |
Note: Python implementation lives at LlamaIndex (Python).