Logo
Getting Started/Installation

Server APIs & Backends

Deploy LlamaIndex.TS in server environments like Express, Fastify, and standalone Node.js applications.

This guide covers adding LlamaIndex.TS agents to traditional server environments where you have full Node.js runtime access.

Supported Runtimes

LlamaIndex.TS works seamlessly with:

  • Node.js (v18+)
  • Bun (v1.0+)
  • Deno (v1.30+)

Common Server Frameworks

Express.js

import express from 'express';
import { agent } from '@llamaindex/workflow';
import { tool } from 'llamaindex';
import { openai } from '@llamaindex/openai';
import { z } from 'zod';

const app = express();
app.use(express.json());

// Initialize agent once at startup
let myAgent: any;

async function initializeAgent() {
  // Create tools for the agent
  const sumTool = tool({
    name: "sum",
    description: "Adds two numbers",
    parameters: z.object({
      a: z.number(),
      b: z.number(),
    }),
    execute: ({ a, b }) => a + b,
  });

  const multiplyTool = tool({
    name: "multiply",
    description: "Multiplies two numbers",
    parameters: z.object({
      a: z.number(),
      b: z.number(),
    }),
    execute: ({ a, b }) => a * b,
  });

  // Create the agent
  myAgent = agent({
    tools: [sumTool, multiplyTool],
    llm: openai({ model: "gpt-4o-mini" }),
  });
}

app.post('/api/chat', async (req, res) => {
  try {
    const { message } = req.body;
    const result = await myAgent.run(message);
    res.json({ response: result.result });
  } catch (error) {
    res.status(500).json({ error: 'Chat failed' });
  }
});

// Initialize and start server
initializeAgent().then(() => {
  app.listen(3000, () => {
    console.log('Server running on port 3000');
  });
});

Fastify

import Fastify from 'fastify';
import { agent } from '@llamaindex/workflow';
import { tool } from 'llamaindex';
import { openai } from '@llamaindex/openai';
import { z } from 'zod';

const fastify = Fastify();
let myAgent: any;

async function initializeAgent() {
  const sumTool = tool({
    name: "sum",
    description: "Adds two numbers",
    parameters: z.object({
      a: z.number(),
      b: z.number(),
    }),
    execute: ({ a, b }) => a + b,
  });

  myAgent = agent({
    tools: [sumTool],
    llm: openai({ model: "gpt-4o-mini" }),
  });
}

fastify.post('/api/chat', async (request, reply) => {
  try {
    const { message } = request.body as { message: string };
    const result = await myAgent.run(message);
    return { response: result.result };
  } catch (error) {
    reply.status(500).send({ error: 'Chat failed' });
  }
});

const start = async () => {
  await initializeAgent();
  await fastify.listen({ port: 3000 });
  console.log('Server running on port 3000');
};

start();

Hono

import { Hono } from "hono";
import { agent } from "@llamaindex/workflow";
import { tool } from "llamaindex";
import { openai } from "@llamaindex/openai";
import { z } from "zod";

type Bindings = {
  OPENAI_API_KEY: string;
};

const app = new Hono<{ Bindings: Bindings }>();

app.post("/api/chat", async (c) => {
  const { setEnvs } = await import("@llamaindex/env");
  setEnvs(c.env);
  
  const { message } = await c.req.json();
  
  const greetTool = tool({
    name: "greet",
    description: "Greets a user",
    parameters: z.object({
      name: z.string(),
    }),
    execute: ({ name }) => `Hello, ${name}!`,
  });

  const myAgent = agent({
    tools: [greetTool],
    llm: openai({ model: "gpt-4o-mini" }),
  });
  
  try {
    const result = await myAgent.run(message);
    return c.json({ response: result.result });
  } catch (error) {
    return c.json({ error: error.message }, 500);
  }
});

export default app;

Streaming Responses

For real-time agent responses:

import { agentStreamEvent } from "@llamaindex/workflow";

app.post('/api/chat-stream', async (req, res) => {
  const { message } = req.body;
  
  res.writeHead(200, {
    'Content-Type': 'text/plain',
    'Transfer-Encoding': 'chunked',
  });
  
  try {
    const context = myAgent.runStream(message);
    
    for await (const event of context) {
      if (agentStreamEvent.include(event)) {
        res.write(event.data.delta);
      }
    }
    
    res.end();
  } catch (error) {
    res.write('Error: ' + error.message);
    res.end();
  }
});

Next Steps

Edit on GitHub

Last updated on