LlamaIndex Tutorial (TypeScript): parsing structured output for advanced developers

This tutorial shows how to make LlamaIndex in TypeScript return structured data instead of free-form text, then parse that output into a typed object you can trust in downstream code. You need this when your agent is feeding a workflow, database, or API that expects predictable fields like status, amount, or riskLevel.

What You'll Need

• •Node.js 18+ installed
• •A TypeScript project with ts-node or tsx
• •llamaindex package
• •An OpenAI API key
• •Basic familiarity with LlamaIndex chat/LLM calls
• •A terminal and a .env file for secrets

Install the dependencies:

npm install llamaindex dotenv zod
npm install -D typescript tsx @types/node

Set your environment variable:

OPENAI_API_KEY=your_key_here

Step-by-Step

1. •Start with a typed schema.

If you want reliable structured output, define the shape first. Zod gives you runtime validation and TypeScript inference from the same source of truth.

import { z } from "zod";

export const ClaimSummarySchema = z.object({
  claimId: z.string(),
  customerName: z.string(),
  status: z.enum(["approved", "pending", "rejected"]),
  amount: z.number(),
  notes: z.array(z.string()),
});

export type ClaimSummary = z.infer<typeof ClaimSummarySchema>;

2. •Create an LLM-backed structured prediction call.

LlamaIndex’s structuredPredict lets you ask for JSON-like output that matches your schema. This is the part that replaces fragile string parsing.

import "dotenv/config";
import { OpenAI } from "@llamaindex/openai";
import { structuredPredict } from "llamaindex";
import { ClaimSummarySchema } from "./schema";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

async function main() {
  const result = await structuredPredict(
    llm,
    ClaimSummarySchema,
    "Summarize this insurance claim: claim CLM-2049 for Priya Shah was approved for $4200. Notes: police report received, photos attached."
  );

  console.log(result);
}

main();

3. •Use the parsed object like normal TypeScript data.

Once parsed, the output is not a blob of text anymore. You can branch on fields, persist them, or pass them into another service without manual cleanup.

import "dotenv/config";
import { OpenAI } from "@llamaindex/openai";
import { structuredPredict } from "llamaindex";
import { ClaimSummarySchema, type ClaimSummary } from "./schema";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

async function run(): Promise<void> {
  const claim: ClaimSummary = await structuredPredict(
    llm,
    ClaimSummarySchema,
    "Claim CLM-2049 for Priya Shah was approved for $4200. Notes: police report received, photos attached."
  );

  if (claim.status === "approved" && claim.amount > 3000) {
    console.log(`Escalate ${claim.claimId} for manual review`);
  }

  console.log(claim.customerName.toUpperCase());
}

run();

4. •Add validation so bad model output fails fast.

Even with structured prompting, you still want runtime checks at the edge. Zod will reject malformed values before they leak into your workflow.

import { ClaimSummarySchema } from "./schema";

const candidate = {
  claimId: "CLM-2049",
  customerName: "Priya Shah",
  status: "approved",
  amount: 4200,
  notes: ["police report received", "photos attached"],
};

const parsed = ClaimSummarySchema.safeParse(candidate);

if (!parsed.success) {
  console.error(parsed.error.flatten());
  process.exit(1);
}

console.log("Validated:", parsed.data.claimId);

5. •Wrap it in a reusable parser function.

In production, you do not want schema logic scattered across handlers. Keep one function responsible for prediction plus validation so every caller gets the same contract.

import { OpenAI } from "@llamaindex/openai";
import { structuredPredict } from "llamaindex";
import { ClaimSummarySchema, type ClaimSummary } from "./schema";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

export async function parseClaimSummary(input: string): Promise<ClaimSummary> {
  return structuredPredict(llm, ClaimSummarySchema, input);
}

Testing It

Run the script with npx tsx src/index.ts and confirm you get an object with claimId, customerName, status, amount, and notes. The key thing to verify is that status is one of the allowed enum values and amount is a number, not a string like "4200".

Test one invalid prompt too, such as asking for a status outside the enum or omitting notes. If your schema is wired correctly, Zod should fail during parsing instead of letting bad data continue downstream.

If you are integrating this into an agent pipeline, log both the raw input and parsed output during development. That makes it much easier to debug whether failures come from prompt quality, schema design, or model behavior.

Next Steps

• •Add nested schemas for line items, policy metadata, or KYC attributes
• •Combine structured output with tool calling for multi-step agent workflows
• •Store validated objects in Postgres using a typed repository layer

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.