LlamaIndex Tutorial (TypeScript): running agents in parallel for beginners

This tutorial shows you how to run multiple LlamaIndex agents in parallel from TypeScript and collect their results in one place. You need this when one agent is too slow, or when you want independent workers for retrieval, classification, and summarization at the same time.

What You'll Need

• •Node.js 18+ installed
• •A TypeScript project with ts-node or a build step
• •@llamaindex/openai
• •llamaindex
• •An OpenAI API key in OPENAI_API_KEY
• •Basic familiarity with AgentWorkflow and tools in LlamaIndex
• •A terminal that can run npm or pnpm

Step-by-Step

1. •Install the packages and set up your environment.
   This example uses the official LlamaIndex TypeScript packages plus OpenAI for the model backend.

npm install llamaindex @llamaindex/openai
npm install -D typescript ts-node @types/node
export OPENAI_API_KEY="your-api-key"

2. •Create a small toolset that each agent can use.
   Parallel agents work best when each one has a narrow job, so here we define two simple tools: one for product lookup and one for risk scoring.

import { tool } from "llamaindex";

export const lookupProduct = tool(
  async ({ sku }: { sku: string }) => {
    return `Product ${sku}: premium checking account, fee $12/month, APY 3.2%`;
  },
  {
    name: "lookup_product",
    description: "Look up product details by SKU",
    parameters: {
      type: "object",
      properties: {
        sku: { type: "string" },
      },
      required: ["sku"],
    },
  }
);

export const scoreRisk = tool(
  async ({ customerType }: { customerType: string }) => {
    const score = customerType === "enterprise" ? "low" : "medium";
    return `Risk score for ${customerType}: ${score}`;
  },
  {
    name: "score_risk",
    description: "Score customer risk by segment",
    parameters: {
      type: "object",
      properties: {
        customerType: { type: "string" },
      },
      required: ["customerType"],
    },
  }
);

3. •Build two agents that can run independently.
   Each agent gets its own system prompt and tool list. The key point is that they do not depend on each other, so they can be executed in parallel with Promise.all().

import { OpenAI } from "@llamaindex/openai";
import { FunctionAgent } from "llamaindex";
import { lookupProduct, scoreRisk } from "./tools";

const llm = new OpenAI({
  model: "gpt-4o-mini",
});

export const productAgent = new FunctionAgent({
  llm,
  tools: [lookupProduct],
  systemPrompt:
    "You are a product specialist. Use the lookup tool and answer concisely.",
});

export const riskAgent = new FunctionAgent({
  llm,
  tools: [scoreRisk],
  systemPrompt:
    "You are a risk analyst. Use the scoring tool and answer concisely.",
});

4. •Run both agents at the same time and wait for both outputs.
   This is the actual parallel pattern. Promise.all() starts both workflows immediately and resolves once both finish.

import { productAgent, riskAgent } from "./agents";

async function main() {
  const [productResult, riskResult] = await Promise.all([
    productAgent.run("Tell me about SKU CHK-1001"),
    riskAgent.run("Assess an enterprise customer"),
  ]);

  console.log("PRODUCT RESULT:");
  console.log(productResult.response);

  console.log("\nRISK RESULT:");
  console.log(riskResult.response);
}

main().catch(console.error);

5. •Add a coordinator step to combine the outputs into one final answer.
   In production, you usually do not stop at parallel execution. You gather results from each specialist agent, then pass them into a final synthesis step.

import { OpenAI } from "@llamaindex/openai";
import { FunctionAgent } from "llamaindex";

const llm = new OpenAI({ model: "gpt-4o-mini" });

const coordinator = new FunctionAgent({
  llm,
  tools: [],
  systemPrompt:
    "You combine specialist outputs into one short client-ready summary.",
});

async function summarize() {
  const [productResult, riskResult] = await Promise.all([
    productAgent.run("Tell me about SKU CHK-1001"),
    riskAgent.run("Assess an enterprise customer"),
  ]);

  const finalAnswer = await coordinator.run(`
Product output:
${productResult.response}

Risk output:
${riskResult.response}

Write a single summary for a bank operations manager.
`);

  console.log(finalAnswer.response);
}

summarize().catch(console.error);

Testing It

Run the script once and confirm that both agent calls complete without waiting on each other sequentially. If you add timestamps before each call, you should see both requests start at nearly the same time.

Also check that each agent only uses its own tool. The product agent should not try to score risk, and the risk agent should not look up products.

If one call fails, Promise.all() will reject immediately. That is fine for learning, but in production you may want Promise.allSettled() so one failed worker does not take down the whole request.

Next Steps

• •Learn how to use Promise.allSettled() for partial-failure workflows
• •Add a router agent that decides which specialists should run in parallel
• •Move from simple tools to retrieval-backed agents with vector indexes

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.