LlamaIndex Tutorial (TypeScript): testing agents locally for beginners

This tutorial shows you how to run a LlamaIndex agent locally in TypeScript, attach a small tool, and test its behavior without wiring it into your app first. You need this when you want fast feedback on prompts, tool calls, and agent routing before shipping anything to production.

What You'll Need

• •Node.js 18+
• •A TypeScript project with ts-node or tsx
• •@llamaindex/openai
• •dotenv
• •An OpenAI API key in OPENAI_API_KEY
• •Basic familiarity with async/await and ES modules

Install the packages:

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

Create a .env file:

OPENAI_API_KEY=your_api_key_here

Step-by-Step

1. •Create a small local project file that loads environment variables and sets up an LLM-backed agent. Keep this isolated from your app code so you can iterate on prompts and tools safely.

import "dotenv/config";
import { openai } from "@llamaindex/openai";
import {
  FunctionTool,
  ReActAgent,
} from "llamaindex";

if (!process.env.OPENAI_API_KEY) {
  throw new Error("Missing OPENAI_API_KEY");
}

const llm = openai({
  model: "gpt-4o-mini",
  temperature: 0,
});

2. •Add one deterministic tool so you can tell whether the agent is actually calling tools or just guessing. For local testing, keep the tool pure and easy to verify.

const getPolicyStatus = FunctionTool.from(
  async ({ policyId }: { policyId: string }) => {
    const records: Record<string, string> = {
      "POL-1001": "active",
      "POL-2002": "pending renewal",
      "POL-3003": "cancelled",
    };

    return records[policyId] ?? "not found";
  },
  {
    name: "get_policy_status",
    description: "Look up the status of an insurance policy by policy ID.",
    parameters: {
      type: "object",
      properties: {
        policyId: { type: "string", description: "Policy ID like POL-1001" },
      },
      required: ["policyId"],
    },
  }
);

3. •Build the agent with a simple system prompt that tells it when to use the tool. This is the part you want to test locally before exposing it to real users.

const agent = new ReActAgent({
  llm,
  tools: [getPolicyStatus],
  context:
    "You are a support assistant for insurance operations. Use tools when the user asks about policy status.",
});

4. •Run a few test queries directly in the terminal. Use one question that should hit the tool and one that should not, so you can compare behavior.

async function main() {
  const queries = [
    "What is the status of policy POL-1001?",
    "Explain what a policy status means in plain English.",
  ];

  for (const query of queries) {
    const response = await agent.chat({ message: query });
    console.log("\nQUERY:", query);
    console.log("ANSWER:", response.message.content);
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

5. •Save the file as src/test-agent.ts and run it locally with tsx. If your tool wiring is correct, the first query should trigger a lookup and the second should be answered from model reasoning alone.

npx tsx src/test-agent.ts

Testing It

The quickest verification is behavioral, not visual. For POL-1001, you should see an answer that resolves to active, which confirms the agent called your tool instead of inventing a value.

If the output looks vague or wrong, check three things first:

• •Your .env file is loaded
• •The tool name and parameter schema match exactly
• •The agent has enough instruction to use tools for status questions

For tighter debugging, change one record in the lookup table and rerun the script. If the answer changes accordingly, your local test harness is working correctly.

Next Steps

• •Add a second tool, such as list_open_claims, and test whether the agent chooses between tools correctly.
• •Wrap this script in Jest or Vitest so you can run regression tests on prompts and tool outputs.
• •Move from hardcoded data to a mocked service layer so you can simulate real backend failures locally

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.