LlamaIndex Tutorial (TypeScript): running agents in parallel for intermediate developers

This tutorial shows you how to run multiple LlamaIndex agents in parallel from TypeScript and combine their results into one response. You need this when a single agent is too slow or too narrow, and you want independent agents to work on different sub-tasks at the same time.

What You'll Need

• •Node.js 18+
• •A TypeScript project with ts-node or tsx
• •llamaindex installed
• •An OpenAI API key exported as OPENAI_API_KEY
• •Basic familiarity with LlamaIndex AgentWorkflow and tools
• •A terminal that can run ES modules or TypeScript directly

Step-by-Step

1. •Install the dependencies and set up your environment.
   This example uses the official LlamaIndex TypeScript package plus a lightweight runtime for executing TypeScript files.

npm init -y
npm install llamaindex
npm install -D typescript tsx @types/node

2. •Create a small tool that each agent can call.
   Keep the tool deterministic so you can see parallel execution clearly. Here we create two tools that simulate separate work streams: one for risk, one for policy.

import { FunctionTool } from "llamaindex";

export const riskTool = FunctionTool.from(
  async ({ query }: { query: string }) => {
    return `Risk analysis for "${query}": medium risk, requires human review.`;
  },
  {
    name: "risk_tool",
    description: "Analyzes a request for risk signals.",
  }
);

export const policyTool = FunctionTool.from(
  async ({ query }: { query: string }) => {
    return `Policy check for "${query}": allowed under current guidelines.`;
  },
  {
    name: "policy_tool",
    description: "Checks whether a request fits policy rules.",
  }
);

3. •Build two agents, each focused on one task.
   The key pattern is separation of concerns: one agent handles risk, the other handles policy. Both can be run independently, then merged later.

import { AgentWorkflow, OpenAI, stepCountIs } from "llamaindex";
import { riskTool, policyTool } from "./tools";

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

export const riskAgent = new AgentWorkflow({
  llm,
  tools: [riskTool],
}).setName("risk-agent");

export const policyAgent = new AgentWorkflow({
  llm,
  tools: [policyTool],
}).setName("policy-agent");

export const guardrail = stepCountIs(3);

4. •Run both agents in parallel with Promise.all.
   This is the part most people miss: you do not need a special “parallel agent” primitive if the workflows are independent. Start both runs together and wait for both results.

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

async function main() {
  const query = "Approve a $25k vendor payment to a new supplier.";

  const [riskResult, policyResult] = await Promise.all([
    riskAgent.run(query),
    policyAgent.run(query),
  ]);

  console.log("RISK:", riskResult);
  console.log("POLICY:", policyResult);
}

main().catch(console.error);

5. •Merge the outputs into a final decision layer.
   In production, this final step usually belongs to a coordinator service or another small agent. Here we just combine the two results into a single response object.

type ParallelDecision = {
  query: string;
  risk: string;
  policy: string;
  decision: "approve" | "review" | "reject";
};

function makeDecision(risk: string, policy: string): ParallelDecision["decision"] {
  if (risk.toLowerCase().includes("high")) return "review";
  if (policy.toLowerCase().includes("not allowed")) return "reject";
  return "approve";
}

const decision: ParallelDecision = {
  query,
  risk: String(riskResult),
  policy: String(policyResult),
  decision: makeDecision(String(riskResult), String(policyResult)),
};

console.log(JSON.stringify(decision, null, 2));

Testing It

Run the script with your preferred TypeScript runtime, for example npx tsx src/main.ts. You should see both agent outputs printed before the final decision object.

To confirm parallelism, add timing logs around each .run() call and around the Promise.all. If both tasks are independent, total runtime should be close to the slower of the two runs, not their sum.

If one agent fails, Promise.all will reject immediately. In production, switch to Promise.allSettled when you want partial results and explicit failure handling.

Next Steps

• •Add a third specialist agent for compliance or fraud screening.
• •Replace the simple merge function with an LLM-based coordinator that writes the final recommendation.
• •Wrap this pattern in an HTTP endpoint so your backend can fan out work across agents per request.

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.