LlamaIndex TypeScript Recipes
Practical recipes for the LlamaIndex.TS workflow API — RAG, multi-agent, streaming and analysis pipelines (project now deprecated upstream).
Practical patterns for the final LlamaIndex.TS releases (versions, checked 2026-11-19). All code uses the functional API — createWorkflow, workflowEvent, handle, run. No class-based extends Workflow or @step() decorators.
Deprecated upstream. LlamaIndex.TS is no longer maintained and its npm packages are marked deprecated. These recipes still work with the final releases; see the overview before starting a new project on it.
Install:
npm install @llamaindex/workflow @llamaindex/core @llamaindex/openai zod # Recipe 1 has its own install lineTable of Contents
Section titled “Table of Contents”- RAG with VectorStoreIndex
- Research Paper Analyser
- Code Documentation Generator
- Multi-Step Analysis Pipeline
- Streaming Workflow with SSE
- Cached RAG Workflow
- Multi-Agent Coordination
- Stateful Conversation Workflow
- Parallel Tool Execution
- Customer Support Triage
- Filtered retrieval and a chat engine
Recipe 1: RAG with VectorStoreIndex
Section titled “Recipe 1: RAG with VectorStoreIndex”Retrieval, answer synthesis and an agent tool from the llamaindex package. Because llamaindex pins its own versions of the scoped packages, install the matching @llamaindex/workflow (see final releases):
npm install llamaindex @llamaindex/openai @llamaindex/workflow@1.1.24import { Document, Settings, VectorStoreIndex, storageContextFromDefaults } from 'llamaindex';import { OpenAI, OpenAIEmbedding } from '@llamaindex/openai';import { agent } from '@llamaindex/workflow';
const llm = new OpenAI({ model: 'gpt-6-luna' });Settings.llm = llm;Settings.embedModel = new OpenAIEmbedding({ model: 'text-embedding-3-small' });
// Build once and persist; later runs load the same directory instead of re-embeddingconst storageContext = await storageContextFromDefaults({ persistDir: './storage' });const index = await VectorStoreIndex.fromDocuments( [ new Document({ text: 'Holiday allowance is 25 days a year.', metadata: { file: 'leave.md' } }), new Document({ text: 'Expenses are reimbursed within 30 days.', metadata: { file: 'expenses.md' } }), ], { storageContext },);
// Retrieval onlyconst retriever = index.asRetriever({ similarityTopK: 2 });for (const hit of await retriever.retrieve({ query: 'How much holiday do I get?' })) { console.log(hit.score?.toFixed(3), hit.node.metadata.file);}
// Retrieval + answer synthesisconst queryEngine = index.asQueryEngine({ similarityTopK: 2 });const response = await queryEngine.query({ query: 'How much holiday do I get?' });console.log(response.toString(), response.sourceNodes?.length);
// As a tool for a workflow agentconst handbookAgent = agent({ llm, tools: [ index.queryTool({ metadata: { name: 'handbook', description: 'Answers questions about the staff handbook.' }, }), ],});const result = await handbookAgent.run('How long do expense claims take?');console.log(result.data.result);storageContextFromDefaults({ persistDir }) writes the docstore, index store and vectors to JSON files. On later runs, build the same storage context and call VectorStoreIndex.init({ storageContext }) to load the index without re-embedding. For larger corpora use one of the vector store integrations instead of the file store.
The other recipes use only @llamaindex/workflow; replace their placeholder retrieval functions with retriever.retrieve(...) from this recipe.
Recipe 2: Research Paper Analyser
Section titled “Recipe 2: Research Paper Analyser”Multi-step pipeline that extracts structured information from academic text.
import { createWorkflow, workflowEvent, run } from '@llamaindex/workflow';import { OpenAI } from '@llamaindex/openai';import { z } from 'zod';
// Zod schema for structured extractionconst PaperSchema = z.object({ title: z.string(), authors: z.array(z.string()), abstract: z.string(), keyFindings: z.array(z.string()), methodology: z.string(), summary: z.string(),});type Paper = z.infer<typeof PaperSchema>;
// Eventsconst textEv = workflowEvent<{ text: string }>();const parsedEv = workflowEvent<{ paper: Paper }>();const reportEv = workflowEvent<{ report: Paper & { analysedAt: string; wordCount: number } }>();
const llm = new OpenAI({ model: 'gpt-6-luna' });
const analyserWorkflow = createWorkflow();
analyserWorkflow.handle([textEv], async (ctx, ev) => { const excerpt = ev.data.text.substring(0, 4_000);
const resp = await llm.complete({ prompt: `Extract the following from the research paper and return valid JSON:title, authors (array), abstract, keyFindings (array), methodology, summary.
Paper text:${excerpt}`, });
const raw = JSON.parse(resp.text); const paper = PaperSchema.parse(raw);
return parsedEv.with({ paper });});
analyserWorkflow.handle([parsedEv], async (ctx, ev) => { const report = { ...ev.data.paper, analysedAt: new Date().toISOString(), wordCount: ev.data.paper.summary.split(' ').length, }; return reportEv.with({ report });});
export async function analysePaper(text: string) { const events = await run(analyserWorkflow, textEv.with({ text })) .until(reportEv) .toArray(); return events.find(e => reportEv.include(e))?.data.report;}Recipe 3: Code Documentation Generator
Section titled “Recipe 3: Code Documentation Generator”Reads TypeScript source files and generates JSDoc-style documentation. It parses the files with the TypeScript compiler API, which is in typescript 5.x (npm install typescript@5); TypeScript 7 does not ship that JavaScript API.
import { createWorkflow, workflowEvent, run } from '@llamaindex/workflow';import { OpenAI } from '@llamaindex/openai';import * as ts from 'typescript';import * as fs from 'node:fs/promises';
interface FunctionSignature { name: string; signature: string;}
// Eventsconst sourceEv = workflowEvent<{ filePath: string }>();const funcsEv = workflowEvent<{ functions: FunctionSignature[] }>();const docsEv = workflowEvent<{ markdown: string }>();
const llm = new OpenAI({ model: 'gpt-6-luna' });
const docGenWorkflow = createWorkflow();
// Step 1 — parse TypeScript ASTdocGenWorkflow.handle([sourceEv], async (ctx, ev) => { const code = await fs.readFile(ev.data.filePath, 'utf-8'); const src = ts.createSourceFile('tmp.ts', code, ts.ScriptTarget.Latest, true);
const functions: FunctionSignature[] = [];
const visit = (node: ts.Node) => { if (ts.isFunctionDeclaration(node) && node.name) { functions.push({ name: node.name.text, signature: code.substring(node.pos, node.end).trim(), }); } ts.forEachChild(node, visit); };
visit(src); return funcsEv.with({ functions });});
// Step 2 — generate docs with LLMdocGenWorkflow.handle([funcsEv], async (ctx, ev) => { const sections = await Promise.all( ev.data.functions.map(async fn => { const resp = await llm.complete({ prompt: `Write a one-paragraph JSDoc description for this TypeScript function:\n\n${fn.signature}`, }); return `### \`${fn.name}\`\n\n${resp.text}\n\n\`\`\`typescript\n${fn.signature}\n\`\`\`\n`; }), );
return docsEv.with({ markdown: `# API Reference\n\n${sections.join('\n')}` });});
export async function generateDocs(filePath: string): Promise<string> { const events = await run(docGenWorkflow, sourceEv.with({ filePath })) .until(docsEv) .toArray(); return events.find(e => docsEv.include(e))?.data.markdown ?? '';}Recipe 4: Multi-Step Analysis Pipeline
Section titled “Recipe 4: Multi-Step Analysis Pipeline”Chains preprocessing, classification, and enrichment steps.
import { createWorkflow, workflowEvent, run, createStatefulMiddleware,} from '@llamaindex/workflow';import { OpenAI } from '@llamaindex/openai';
// Eventsconst rawEv = workflowEvent<{ text: string; id: string }>();const cleanedEv = workflowEvent<{ text: string; id: string }>();const classifiedEv = workflowEvent<{ text: string; id: string; category: string }>();const enrichedEv = workflowEvent<{ id: string; category: string; summary: string; sentiment: string;}>();
// Per-run state (each run() gets a fresh copy; aggregate across runs yourself)const { withState } = createStatefulMiddleware<{ processed: number; failedIds: string[] }>( () => ({ processed: 0, failedIds: [] }),);
const base = createWorkflow();const pipeline = withState(base);const llm = new OpenAI({ model: 'gpt-6-luna' });
// Step 1 — clean textpipeline.handle([rawEv], async (ctx, ev) => { const text = ev.data.text.trim().replace(/\s+/g, ' '); return cleanedEv.with({ text, id: ev.data.id });});
// Step 2 — classifypipeline.handle([cleanedEv], async (ctx, ev) => { const resp = await llm.complete({ prompt: `Classify into one word: TECHNICAL, BUSINESS, LEGAL, SUPPORT.\n\n${ev.data.text}`, }); return classifiedEv.with({ text: ev.data.text, id: ev.data.id, category: resp.text.trim().toUpperCase(), });});
// Step 3 — enrichpipeline.handle([classifiedEv], async (ctx, ev) => { const [summaryResp, sentimentResp] = await Promise.all([ llm.complete({ prompt: `Summarise in one sentence:\n${ev.data.text}` }), llm.complete({ prompt: `Is this POSITIVE, NEUTRAL, or NEGATIVE?\n${ev.data.text}` }), ]);
ctx.state.processed += 1;
return enrichedEv.with({ id: ev.data.id, category: ev.data.category, summary: summaryResp.text.trim(), sentiment: sentimentResp.text.trim(), });});
export async function processBatch(items: Array<{ id: string; text: string }>) { return Promise.all( items.map(async item => { const events = await run(pipeline, rawEv.with(item)) .until(enrichedEv) .toArray(); return events.find(e => enrichedEv.include(e))?.data; }), );}Recipe 5: Streaming Workflow with SSE
Section titled “Recipe 5: Streaming Workflow with SSE”Emit intermediate progress events to an Express SSE endpoint.
import express, { Request, Response } from 'express';import { createWorkflow, workflowEvent, run } from '@llamaindex/workflow';
// Eventsconst jobEv = workflowEvent<{ jobId: string; query: string }>();const progressEv = workflowEvent<{ jobId: string; step: string; pct: number }>();const resultEv = workflowEvent<{ jobId: string; answer: string }>();
const processingWorkflow = createWorkflow();
processingWorkflow.handle([jobEv], async (ctx, ev) => { const { jobId, query } = ev.data;
ctx.sendEvent(progressEv.with({ jobId, step: 'Retrieving documents', pct: 20 })); await new Promise(r => setTimeout(r, 50)); // simulate async work
ctx.sendEvent(progressEv.with({ jobId, step: 'Generating answer', pct: 70 })); await new Promise(r => setTimeout(r, 50));
return resultEv.with({ jobId, answer: `Answer for: ${query}` });});
// Express SSE endpointconst app = express();app.use(express.json());
app.post('/api/query/stream', async (req: Request, res: Response) => { const { query } = req.body as { query: string }; const jobId = `job-${Date.now()}`;
res.setHeader('Content-Type', 'text/event-stream'); res.setHeader('Cache-Control', 'no-cache'); res.setHeader('Connection', 'keep-alive'); res.flushHeaders();
const send = (data: unknown) => res.write(`data: ${JSON.stringify(data)}\n\n`);
try { for await (const ev of run(processingWorkflow, jobEv.with({ jobId, query }))) { if (progressEv.include(ev)) { send({ type: 'progress', ...ev.data }); } else if (resultEv.include(ev)) { send({ type: 'result', ...ev.data }); break; } } } catch (err) { send({ type: 'error', message: String(err) }); }
res.end();});
app.listen(3000, () => console.log('Listening on :3000'));Recipe 6: Cached RAG Workflow
Section titled “Recipe 6: Cached RAG Workflow”Wraps workflow logic with a Redis-backed cache check before hitting the LLM.
import { createWorkflow, workflowEvent, run,} from '@llamaindex/workflow';import { createHash } from 'node:crypto';
// Redis-compatible cache interface (use ioredis in production)interface Cache { get(key: string): Promise<string | null>; set(key: string, value: string, ttlSecs: number): Promise<void>;}
// Eventsconst requestEv = workflowEvent<{ query: string }>();const cacheHitEv = workflowEvent<{ answer: string; fromCache: true }>();const cacheMissEv = workflowEvent<{ query: string; cacheKey: string }>();const answeredEv = workflowEvent<{ answer: string; fromCache: boolean }>();
function buildCachedWorkflow(cache: Cache) { const wf = createWorkflow();
// Route: cache hit or miss wf.handle([requestEv], async (ctx, ev) => { const key = `rag:${createHash('md5').update(ev.data.query.toLowerCase()).digest('hex')}`; const cached = await cache.get(key);
if (cached) { return cacheHitEv.with({ answer: cached, fromCache: true }); } return cacheMissEv.with({ query: ev.data.query, cacheKey: key }); });
// Cache hit path wf.handle([cacheHitEv], async (ctx, ev) => { return answeredEv.with({ answer: ev.data.answer, fromCache: true }); });
// Cache miss path — run RAG, then store wf.handle([cacheMissEv], async (ctx, ev) => { const answer = await runRag(ev.data.query); // your RAG logic await cache.set(ev.data.cacheKey, answer, 3_600); return answeredEv.with({ answer, fromCache: false }); });
return wf;}
async function runRag(query: string): Promise<string> { return `LLM answer for: ${query}`;}
export async function queryWithCache(cache: Cache, query: string) { const wf = buildCachedWorkflow(cache); const events = await run(wf, requestEv.with({ query })) .until(answeredEv) .toArray(); return events.find(e => answeredEv.include(e))?.data;}Recipe 7: Multi-Agent Coordination
Section titled “Recipe 7: Multi-Agent Coordination”Two FunctionAgent specialists that hand off between each other.
import { FunctionAgent, multiAgent } from '@llamaindex/workflow';import { OpenAI } from '@llamaindex/openai';import { tool } from '@llamaindex/core/tools';import { z } from 'zod';
const llm = new OpenAI({ model: 'gpt-6-luna' });
// Tool definitionsconst searchTool = tool({ name: 'search', description: 'Search for information on a topic', parameters: z.object({ query: z.string() }), execute: async ({ query }) => `Search result: ${query}`,});
const summariseTool = tool({ name: 'summarise', description: 'Summarise a block of text', parameters: z.object({ text: z.string() }), execute: async ({ text }) => `Summary of: ${text.substring(0, 80)}...`,});
// Agentsconst researcher = new FunctionAgent({ name: 'Researcher', description: 'Searches for and retrieves factual information', systemPrompt: 'Research the topic thoroughly, then hand off to Analyst.', llm, tools: [searchTool], canHandoffTo: ['Analyst'],});
const analyst = new FunctionAgent({ name: 'Analyst', description: 'Analyses information and produces concise reports', systemPrompt: 'Analyse the research and produce a structured summary.', llm, tools: [summariseTool], canHandoffTo: [],});
// Composeconst researchPipeline = multiAgent({ agents: [researcher, analyst], rootAgent: researcher,});
export async function runResearch(question: string) { const stop = await researchPipeline.run(question); // resolves to the stop event return stop.data.result;}
// runResearch('Latest developments in RAG pipelines?').then(console.log);Recipe 8: Stateful Conversation Workflow
Section titled “Recipe 8: Stateful Conversation Workflow”Maintains per-session message history across multiple turns. Each run() creates a fresh workflow context, so state set up with createStatefulMiddleware lasts for one run only; conversation history that must survive between turns belongs in your own session store (here a Map; in production Redis or a database), passed in with each turn.
import { createWorkflow, workflowEvent, run } from '@llamaindex/workflow';import { OpenAI } from '@llamaindex/openai';import type { ChatMessage } from '@llamaindex/core/llms';
// Eventsconst turnEv = workflowEvent<{ history: ChatMessage[]; userMessage: string }>();const replyEv = workflowEvent<{ assistant: string; history: ChatMessage[] }>();
const convWf = createWorkflow();const llm = new OpenAI({ model: 'gpt-6-luna' });
convWf.handle([turnEv], async (ctx, ev) => { const history: ChatMessage[] = [...ev.data.history, { role: 'user', content: ev.data.userMessage }]; const resp = await llm.chat({ messages: history }); const reply = String(resp.message.content); return replyEv.with({ assistant: reply, history: [...history, { role: 'assistant', content: reply }] });});
const sessions = new Map<string, ChatMessage[]>();
export async function chat(sessionId: string, userMessage: string): Promise<string> { const events = await run(convWf, turnEv.with({ history: sessions.get(sessionId) ?? [], userMessage })) .until(replyEv) .toArray(); const reply = events.find(e => replyEv.include(e)); if (!reply || !replyEv.include(reply)) return ''; sessions.set(sessionId, reply.data.history); return reply.data.assistant;}Recipe 9: Parallel Tool Execution
Section titled “Recipe 9: Parallel Tool Execution”Fan out to multiple tools in a single handler, then aggregate the results.
import { createWorkflow, workflowEvent, run } from '@llamaindex/workflow';
// Simulated toolsasync function webSearch(query: string) { return `Web: ${query}`; }async function dbLookup(query: string) { return `DB: ${query}`; }async function vectorSearch(query: string) { return `Vec: ${query}`; }
// Eventsconst searchEv = workflowEvent<{ query: string }>();const mergedEv = workflowEvent<{ results: string[]; query: string }>();
const parallelWf = createWorkflow();
parallelWf.handle([searchEv], async (ctx, ev) => { // All three tools run concurrently const [web, db, vec] = await Promise.all([ webSearch(ev.data.query), dbLookup(ev.data.query), vectorSearch(ev.data.query), ]);
return mergedEv.with({ results: [web, db, vec], query: ev.data.query });});
export async function multiSearch(query: string) { const events = await run(parallelWf, searchEv.with({ query })) .until(mergedEv) .toArray(); return events.find(e => mergedEv.include(e))?.data.results;}Recipe 10: Customer Support Triage
Section titled “Recipe 10: Customer Support Triage”Routes support tickets to specialist agents based on category.
import { createWorkflow, workflowEvent, run,} from '@llamaindex/workflow';import { OpenAI } from '@llamaindex/openai';
type Category = 'BILLING' | 'TECHNICAL' | 'ACCOUNT' | 'OTHER';
// Eventsconst ticketEv = workflowEvent<{ id: string; body: string }>();const billingEv = workflowEvent<{ id: string; body: string }>();const technicalEv = workflowEvent<{ id: string; body: string }>();const otherEv = workflowEvent<{ id: string; body: string }>();const resolvedEv = workflowEvent<{ id: string; category: Category; response: string }>();
const llm = new OpenAI({ model: 'gpt-6-luna' });
const triageWorkflow = createWorkflow();
// Step 1 — classify tickettriageWorkflow.handle([ticketEv], async (ctx, ev) => { const resp = await llm.complete({ prompt: `Classify this support ticket into BILLING, TECHNICAL, ACCOUNT, or OTHER.\nRespond with just one word.\n\n${ev.data.body}`, });
const cat = resp.text.trim().toUpperCase() as Category; const payload = { id: ev.data.id, body: ev.data.body };
if (cat === 'BILLING') return billingEv.with(payload); if (cat === 'TECHNICAL') return technicalEv.with(payload); return otherEv.with(payload);});
// Billing specialisttriageWorkflow.handle([billingEv], async (ctx, ev) => { const resp = await llm.complete({ prompt: `You are a billing specialist. Respond to this support ticket:\n${ev.data.body}`, }); return resolvedEv.with({ id: ev.data.id, category: 'BILLING', response: resp.text });});
// Technical specialisttriageWorkflow.handle([technicalEv], async (ctx, ev) => { const resp = await llm.complete({ prompt: `You are a technical support specialist. Respond to this support ticket:\n${ev.data.body}`, }); return resolvedEv.with({ id: ev.data.id, category: 'TECHNICAL', response: resp.text });});
// General handler (ACCOUNT and OTHER)triageWorkflow.handle([otherEv], async (ctx, ev) => { const resp = await llm.complete({ prompt: `You are a customer support agent. Respond helpfully to:\n${ev.data.body}`, }); return resolvedEv.with({ id: ev.data.id, category: 'OTHER', response: resp.text });});
export async function triageTicket(id: string, body: string) { const events = await run(triageWorkflow, ticketEv.with({ id, body })) .until(resolvedEv) .toArray(); return events.find(e => resolvedEv.include(e))?.data;}Recipe 11: Filtered retrieval and a chat engine
Section titled “Recipe 11: Filtered retrieval and a chat engine”The llamaindex package also has what Recipe 1 does not show: chunking settings, metadata filters on a retriever, and a chat engine that keeps the conversation. Install as in Recipe 1.
import { ContextChatEngine, Document, FilterOperator, SentenceSplitter, Settings, VectorStoreIndex, type MetadataFilters,} from 'llamaindex';import { OpenAI, OpenAIEmbedding } from '@llamaindex/openai';
const llm = new OpenAI({ model: 'gpt-6-luna' });Settings.llm = llm;Settings.embedModel = new OpenAIEmbedding({ model: 'text-embedding-3-small' });Settings.nodeParser = new SentenceSplitter({ chunkSize: 256, chunkOverlap: 32 });
const index = await VectorStoreIndex.fromDocuments([ new Document({ text: 'Staff receive 25 days of paid holiday a year.', metadata: { department: 'hr', file: 'leave.md' } }), new Document({ text: 'Production deployments need two approvals.', metadata: { department: 'engineering', file: 'deploy.md' } }),]);
const hrOnly: MetadataFilters = { filters: [{ key: 'department', operator: FilterOperator.EQ, value: 'hr' }],};
// Retrieval restricted by metadataconst retriever = index.asRetriever({ similarityTopK: 3, filters: hrOnly });for (const hit of await retriever.retrieve({ query: 'How much holiday do I get?' })) { console.log(hit.score?.toFixed(3), hit.node.metadata.file);}
// A chat engine over the same retriever keeps the conversationconst chat = new ContextChatEngine({ retriever, chatModel: llm, systemPrompt: 'Answer from the context. Say so when the context does not answer.',});const first = await chat.chat({ message: 'How much holiday do I get?' });console.log(first.message.content, first.sourceNodes?.length);const second = await chat.chat({ message: 'And does that include bank holidays?' });console.log(second.message.content);
// Streamingconst stream = await chat.chat({ message: 'Summarise that in five words.', stream: true });for await (const chunk of stream) process.stdout.write(chunk.delta);console.log();await chat.reset();Notes:
Settings.nodeParsersets the chunking for every index built afterwards.SentenceSplitterkeeps sentences together; the other parsers (MarkdownNodeParser,SentenceWindowNodeParser,TokenTextSplitter) are in the same package.filterstakes the same shape the vector stores use: a list of{ key, operator, value }and an optionalcondition('and'or'or'). Operators include==,!=,>,>=,<,<=,in,nin,any,all,containsandtext_match; each vector store supports a subset, so check the store you use. Filtering happens in the retriever, so other departments’ text never reaches the prompt.ContextChatEngineretrieves for each message, puts the context in the system prompt and keeps the history in its memory. Create one per conversation;chat.reset()clears it.index.asChatEngine(...)is a shortcut that builds aContextChatEngineover the index’s default retriever.chat({ message, stream: true })returns an async iterable of chunks with adelta; withoutstreamit resolves to a single response withmessage.contentandsourceNodes.
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-10-24 | final releases | Added Recipe 11 (metadata-filtered retrieval, chunking settings and a chat engine), type-checked with tsc --strict and run against a stubbed OpenAI endpoint. |
| 2026-10-21 | final releases | Recipe 1 replaced: it stubbed retrieval; it now builds a real VectorStoreIndex with a retriever, a query engine and an agent tool (run with fake models). Unused or imports removed. |
| 2026-10-21 | @llamaindex/workflow 1.1.25 | Deprecation notice added. Recipe 7 tools switched to Zod schemas and run() usage corrected; Recipe 8 rewritten (state middleware does not persist between runs, and ChatMessage is exported from @llamaindex/core/llms, not @llamaindex/openai). Model names updated. |
| 2026-05-24 | @llamaindex/workflow 1.1.25 | Full rewrite — previous recipes used llama-index-workflows (non-existent package), extends Workflow, @step(), new StartEvent, new StopEvent, workflow.run(). All replaced with functional API: createWorkflow, workflowEvent, handle, run. 10 recipes rewritten, API verified against installed @llamaindex/workflow@1.1.25 in .routine-envs/check-0524-node. |
| April 2026 | 1.1.24 | Initial recipes using incorrect class-based API. |