LlamaIndex Tutorial (TypeScript): testing agents locally for advanced developers

This tutorial shows you how to run a LlamaIndex agent locally in TypeScript, wire it to a deterministic test harness, and validate tool calls without depending on a live app shell. You need this when you want repeatable agent tests before wiring the agent into an API, queue worker, or bank/insurance workflow.

What You'll Need

• •Node.js 18+ and npm
• •A TypeScript project with tsconfig.json
• •llamaindex installed
• •An OpenAI API key for the default LLM used by the agent
• •A local .env file for secrets
• •Basic familiarity with async/await and TypeScript classes

Install the package:

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

Set your environment variable:

OPENAI_API_KEY=your_key_here

Step-by-Step

1. •Create a minimal local agent setup with one deterministic tool. The point is not to build a feature-rich assistant yet; it is to make tool behavior observable and testable from the command line.

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

const weatherTool = FunctionTool.from(
  async (city: string) => {
    return `Weather in ${city}: 18C and cloudy`;
  },
  {
    name: "get_weather",
    description: "Get the current weather for a city",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string" },
      },
      required: ["city"],
    },
  }
);

const llm = new OpenAI({ model: "gpt-4o-mini" });
const agent = new ReActAgent({
  tools: [weatherTool],
  llm,
});

2. •Wrap the agent in a small runner so you can invoke it locally from Node. This gives you a stable entry point for manual checks and later for automated tests.

async function main() {
  const response = await agent.chat({
    message: "What's the weather in Nairobi?",
  });

  console.log(String(response));
}

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

3. •Add a local assertion layer so you can verify tool usage instead of only reading model output. In production, this is the difference between “the answer looks right” and “the agent actually called the right tool.”

import assert from "node:assert/strict";

async function testWeatherFlow() {
  const response = await agent.chat({
    message: "What's the weather in Nairobi?",
  });

  const text = String(response);
  assert.ok(text.length > 0, "Agent returned empty output");
  assert.match(text.toLowerCase(), /nairobi|weather|cloudy|18c/);
}

testWeatherFlow().then(() => {
  console.log("Local test passed");
});

4. •Run the file with tsx so you get fast iteration without compiling first. For advanced developers, this is usually enough for local behavior checks before moving into Vitest or Jest.

{
  "name": "llamaindex-agent-test",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "tsx src/agent-test.ts"
  }
}

npm run dev

5. •If you want stronger local testing, isolate your tool logic and test it directly before involving the LLM. That gives you deterministic coverage for business rules, which matters when your agent is handling claims, policy data, or internal operations.

import assert from "node:assert/strict";

async function getWeather(city: string) {
  return `Weather in ${city}: 18C and cloudy`;
}

async function testToolOnly() {
  const result = await getWeather("Nairobi");
  assert.equal(result, "Weather in Nairobi: 18C and cloudy");
}

testToolOnly().then(() => console.log("Tool test passed"));

Testing It

Run the script twice with the same prompt and confirm that the tool output stays stable. If your model sometimes answers directly and sometimes calls the tool, tighten the prompt or move more logic into deterministic tools.

For deeper verification, log both the final response and any tool outputs inside your tool function. In real projects, I also snapshot these results in Vitest so regressions are obvious when prompts or models change.

If the agent fails locally, check three things first: OPENAI_API_KEY, Node version, and whether your package is using ESM ("type": "module"). Most local failures come from runtime configuration, not LlamaIndex itself.

Next Steps

• •Add Vitest around your tool functions and agent prompts.
• •Replace the single weather tool with domain tools like policy lookup or claims status.
• •Learn how to persist conversation state and memory between runs with LlamaIndex storage patterns.

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.