Build a support agent

In this tutorial you extend the quickstart agent into a support agent for an online shop. It looks up orders and opens tickets from data the platform stores for it, receives order events through a webhook, posts a daily ticket count, answers from uploaded policy documents, and runs on your website. Each step adds one primitive and tests it on its own; only the last two steps touch production. Finished, it answers like this in production:

Output

Order A-1001 has shipped, as of a moment ago. Anything else you'd like me to check on it?

Plan about 30 minutes. You need the project from the quickstart, signed in, with agent version 1 promoted. Verified against lua-cli 3.33.0.

What you’ll build

A support skill with two tools: lookup_order reads an order from Data, and create_ticket writes one.
An order-status webhook that stores each order event so lookup_order has something to find.
A persona in object form, with separate instructions for text channels and voice calls.
Knowledge Search over documents you upload in the admin dashboard.
A daily-summary job that counts open tickets every morning.
A released agent version, embedded on a web page with the chat widget.

Code: Add a support skill with two tools

Both tools use Data, the agent-scoped JSON store; collections (orders, tickets) are created on first write. Data.get takes the collection, a filter, a page number, and a page size, and returns { data, pagination }; each entry keeps your fields under data. lookup_order returns { found: false } instead of throwing, because the model reads the return value and the skill’s context tells it what to say when the order is missing.

src/skills/tools/LookupOrderTool.ts

import { LuaTool, Data } from 'lua-cli';
import { z } from 'zod';

export default class LookupOrderTool implements LuaTool {
  name = 'lookup_order';
  description = 'Look up the current status of an order by its order number';

  inputSchema = z.object({
    orderId: z.string().describe('Order number, for example "A-1001"'),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Data.get('orders', { orderId: input.orderId }, 1, 1);
    const order = result.data[0];
    if (!order) {
      return { found: false, orderId: input.orderId };
    }
    return { found: true, orderId: input.orderId, status: order.data.status, updatedAt: order.data.updatedAt };
  }
}

create_ticket writes an entry and returns its ID so the model can read it back to the end user. The zod describe() strings are part of what the model sees, so write them as instructions for filling the field.

src/skills/tools/CreateTicketTool.ts

import { LuaTool, Data } from 'lua-cli';
import { z } from 'zod';

export default class CreateTicketTool implements LuaTool {
  name = 'create_ticket';
  description = 'Open a support ticket for an order problem';

  inputSchema = z.object({
    orderId: z.string().describe('Order number the ticket is about'),
    issue: z.string().describe('What went wrong, in the customer\'s words'),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const ticket = await Data.create('tickets', {
      orderId: input.orderId,
      issue: input.issue,
      status: 'open',
      createdAt: new Date().toISOString(),
    });
    return { ticketId: ticket.id, status: 'open' };
  }
}

The skill’s context tells the model when to call each tool and what to do with a miss.

src/skills/support.skill.ts

import { LuaSkill } from 'lua-cli';
import LookupOrderTool from './tools/LookupOrderTool';
import CreateTicketTool from './tools/CreateTicketTool';

export default new LuaSkill({
  name: 'support',
  description: 'Order status lookups and support tickets',
  context: `Use lookup_order when the user asks where an order is or what its status is.
Ask for the order number if the user hasn't given one.
If lookup_order returns found: false, say the order isn't in the system yet and offer to open a ticket.
Use create_ticket when the user reports a problem with an order. Confirm the ticket id back to them.`,
  tools: [new LookupOrderTool(), new CreateTicketTool()],
});

src/index.ts

import { LuaAgent } from 'lua-cli';
import weatherSkill from './skills/weather.skill';
import supportSkill from './skills/support.skill';

const agent = new LuaAgent({
  name: 'docs-quickstart',
  persona: 'You are a weather assistant. Answer in one or two sentences.',
  skills: [weatherSkill, supportSkill],
});

Run create_ticket once. lua test executes your code on your machine, but Data calls reach the platform, so the ticket is stored on the agent.

lua test --ci skill --name create_ticket --input '{"orderId":"A-1001","issue":"Arrived damaged"}'

Output

✅ Selected tool: create_ticket
🚀 Executing tool...
✅ Tool execution successful!

Tool returned: Object — fields: ticketId, status
Output:
{ ticketId: '1d0cdc8a-49b3-4c43-8483-7da3cc240518', status: 'open' }

Run lookup_order for the same order. You should see found: false: nothing has written to orders yet, which the next step fixes.

lua test --ci skill --name lookup_order --input '{"orderId":"A-1001"}'

Output

Tool returned: Object — fields: found, orderId
Output:
{ found: false, orderId: 'A-1001' }

Code: Store order events with a webhook

A webhook is an HTTP endpoint your code handles outside any conversation; no model runs. This one validates the body with zod (a request that fails bodySchema is rejected before execute runs), then creates or updates the order’s entry so the same order number never gets two entries.

src/webhooks/OrderStatusWebhook.ts

import { LuaWebhook, Data } from 'lua-cli';
import { z } from 'zod';

export default new LuaWebhook({
  name: 'order-status',
  description: 'Receives order status events from the order system and stores the latest status',
  bodySchema: z.object({
    orderId: z.string(),
    status: z.enum(['processing', 'shipped', 'delivered', 'cancelled']),
  }),
  execute: async ({ body }) => {
    const updatedAt = new Date().toISOString();
    const existing = await Data.get('orders', { orderId: body.orderId }, 1, 1);
    const order = existing.data[0];
    if (order) {
      await Data.update('orders', order.id, { ...order.data, status: body.status, updatedAt });
      return { orderId: body.orderId, status: body.status, created: false };
    }
    await Data.create('orders', { orderId: body.orderId, status: body.status, updatedAt });
    return { orderId: body.orderId, status: body.status, created: true };
  },
});

src/index.ts

import { LuaAgent } from 'lua-cli';
import weatherSkill from './skills/weather.skill';
import supportSkill from './skills/support.skill';
import orderStatusWebhook from './webhooks/OrderStatusWebhook';

const agent = new LuaAgent({
  name: 'docs-quickstart',
  persona: 'You are a weather assistant. Answer in one or two sentences.',
  skills: [weatherSkill, supportSkill],
  webhooks: [orderStatusWebhook],
});

lua test webhook takes the request as { "query", "headers", "body" } and runs execute with it.

lua test --ci webhook --name order-status --input '{"body":{"orderId":"A-1001","status":"shipped"}}'

Output

✅ Selected webhook: order-status
🚀 Executing webhook...
✅ Webhook execution successful!

Webhook returned: Object — fields: orderId, status, created
Output:
{ orderId: 'A-1001', status: 'shipped', created: true }

Run lookup_order again. You should see the status the webhook stored.

lua test --ci skill --name lookup_order --input '{"orderId":"A-1001"}'

Output

Tool returned: Object — fields: found, orderId, status, updatedAt
Output:
{ found: true, orderId: 'A-1001', status: 'shipped', updatedAt: '2026-09-12T17:24:16.134Z' }

In production, sign the calls: set secret on the webhook and send x-lua-signature; see Handle a webhook.

Code: Write the persona for text and voice

The persona is the text the model reads before every conversation. In object form, base is rendered on every channel, then text is appended on text channels and voice on voice calls. The skill context stays where it is: the persona says who the agent is, the context says when to call which tool.

src/index.ts

import { LuaAgent } from 'lua-cli';
import weatherSkill from './skills/weather.skill';
import supportSkill from './skills/support.skill';
import orderStatusWebhook from './webhooks/OrderStatusWebhook';

const agent = new LuaAgent({
  name: 'docs-quickstart',
  persona: {
    base: `You are the support agent for Acme, an online shop.
Confirm the order number before you act on it. Never invent an order status.
Answer in two sentences or fewer.`,
    text: 'Use plain sentences; no bullet lists or headings.',
    voice: 'Speak the order number digit by digit.',
  },
  skills: [weatherSkill, supportSkill],
  webhooks: [orderStatusWebhook],
});

Talk to the agent in the sandbox. lua chat -e sandbox compiles your code and uploads it as sandbox versions the platform runs; the first run after a new skill registers it on the server and may answer without it (Skipping skill support - no skillId found in lua.skill.yaml), so run the command twice. You should see the model call lookup_order and report the shipped status.

lua chat --ci -e sandbox -m "Where is order A-1001?" -t

Output

💡 Sandbox mode: uses your locally compiled code — no lua push needed.
…
✅ Pushed 2 skills to sandbox
…
Order A-1001 has shipped, as of a few minutes ago. Anything else you'd like me to check on it?

Dashboard: Add knowledge

Knowledge is the set of documents the agent retrieves from while the Knowledge Search feature (rag) is on; it lives on the server, not in your code. Open the agent in the admin dashboard (lua admin opens it), select the Knowledge tab, and upload a document such as your returns policy. You should see the document in the tab’s list once its processing finishes. From the terminal, lua resources list prints the same list.rag retrieves passages from your uploads and puts them in front of the model when a question matches. lua init asks for every capability feature, so the agent normally starts with rag on; confirm from the terminal, where the first entry should read Active.

lua features list

Output

1. ✅ Knowledge Search (RAG)
   Name: rag
   Status: Active
…

If it reads Inactive, turn it on with lua features enable --feature-name rag. Ask the sandbox agent a question the document answers, such as “What is your returns policy?”; it answers from the upload.

Code: Schedule a daily summary job

A job runs on a schedule with no conversation attached, so there is no end user, no thread, and no model unless your code calls one. schedule is cron (with an optional IANA timezone), interval in seconds, or once at a date; timeout is in seconds. This one counts open tickets at 09:00 London time, stores the total, and returns it.

src/jobs/DailySummaryJob.ts

import { LuaJob, Data } from 'lua-cli';

export default new LuaJob({
  name: 'daily-summary',
  description: 'Counts open tickets every morning and stores the total',
  schedule: { type: 'cron', expression: '0 9 * * *', timezone: 'Europe/London' },
  timeout: 60,
  execute: async () => {
    const open = await Data.get('tickets', { status: 'open' }, 1, 1);
    const summary = { openTickets: open.pagination.totalCount, date: new Date().toISOString().slice(0, 10) };
    await Data.create('summaries', summary);
    return summary;
  },
});

src/index.ts

import { LuaAgent } from 'lua-cli';
import weatherSkill from './skills/weather.skill';
import supportSkill from './skills/support.skill';
import orderStatusWebhook from './webhooks/OrderStatusWebhook';
import dailySummaryJob from './jobs/DailySummaryJob';

const agent = new LuaAgent({
  name: 'docs-quickstart',
  persona: {
    base: `You are the support agent for Acme, an online shop.
Confirm the order number before you act on it. Never invent an order status.
Answer in two sentences or fewer.`,
    text: 'Use plain sentences; no bullet lists or headings.',
    voice: 'Speak the order number digit by digit.',
  },
  skills: [weatherSkill, supportSkill],
  webhooks: [orderStatusWebhook],
  jobs: [dailySummaryJob],
});

lua test job runs execute now instead of waiting for the schedule. You should see the ticket from step 1 counted.

lua test --ci job --name daily-summary

Output

✅ Selected job: daily-summary
📅 Schedule: Cron: 0 9 * * * (Europe/London)
✅ Job execution successful!

Job returned: Object — fields: openTickets, date
Output:
{ openTickets: 1, date: '2026-09-12' }

Terminal: Release the agent

lua push all compiles, bumps the patch version of every primitive, uploads each one plus the persona and a source backup, and records the new versions in lua.skill.yaml. The skills, webhook, and job change nothing for end users until you promote; the persona is served from the next message. --force skips the confirmation, and --ci fails instead of prompting.

lua push all --ci --force

Output

📦 Pushing 2 skill(s)...
  ✅ weather v1.0.2 pushed
  ✅ support v1.0.1 pushed

🪝 Pushing 1 webhook(s)...
  ✅ order-status v1.0.1 pushed

⏰ Pushing 1 job(s)...
  ✅ daily-summary v1.0.1 pushed

🌙 Pushing persona...
  ✅ Persona version 2 created
…
✅ Push All Complete!

Snapshot the pushed state as agent version 2, then promote it. A version records which pushed version of each primitive, which persona version, and which model belong together; promoting switches every primitive in one step, and promoting 1 again would roll the code back. lua version list shows which version is active.

lua version create --ci -m "Support skill, order-status webhook, daily summary"
lua version promote 2

Output

✓ Created v2 (staged). Run `lua version promote v2` to deploy.
✓ Promoted v2. Previous active: v1.

From this moment every end user gets version 2, and the job fires at its next 09:00. Roll back with lua version promote 1; see Release an agent to production.

Code: Put the agent on your website

The web widget is the channel end users reach from a browser: one script tag, no build step, and it talks to the same promoted version as lua chat -e production. Set environment: "production" and replace agent_abc123 with the agentId in lua.skill.yaml.

index.html

<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "agent_abc123",
    environment: "production",
  });
</script>

Open the page. You should see a chat button in the bottom-right corner, and “Where is order A-1001?” gets the same answer as lua chat -e production. Colors, position, and welcome text are covered in the web widget quickstart.

Ask production about the order. The answer comes from lookup_order reading the entry your webhook wrote, under the new persona.

lua chat --ci -e production -m "Where is order A-1001?" -t

Output

ℹ️  Thread: 28d6eeaa-fc87-451d-92b6-ebf96d364da6
…
Order A-1001 has shipped, as of a moment ago. Anything else you'd like me to check on it?

Remove the test records

Data is shared by the sandbox and production, so the ticket, order, and summary you created stay on the agent. There is no CLI command for entries; delete them from code with Data.delete(collection, entryId). Add this tool to the support skill, run it once with lua test, then remove it before your next push.

src/skills/tools/ClearTestDataTool.ts

import { LuaTool, Data } from 'lua-cli';
import { z } from 'zod';

export default class ClearTestDataTool implements LuaTool {
  name = 'clear_test_data';
  description = 'Delete every entry in the orders, tickets, and summaries collections';
  inputSchema = z.object({});

  async execute() {
    let deleted = 0;
    for (const collection of ['orders', 'tickets', 'summaries']) {
      const page = await Data.get(collection, {}, 1, 100);
      for (const entry of page.data) {
        await Data.delete(collection, entry.id);
        deleted += 1;
      }
    }
    return { deleted };
  }
}

lua test --ci skill --name clear_test_data --input '{}'

What you learned

A skill’s context plus each tool’s description is how the model decides when to call your code, and lua test runs a tool without a model (About skills and tools).
Data is the agent-scoped store tools, webhooks, and jobs share, which is how a webhook can feed a tool (Data reference).
A webhook handles HTTP outside any conversation, and lua test webhook replays one request locally (About webhooks).
The persona’s object form gives text channels and voice calls different instructions on top of a shared base, and a pushed persona is served at once (About persona).
Knowledge lives on the server and needs the rag feature; uploads and features are managed from the admin dashboard or lua features (About knowledge and features).
A job runs on a cron, interval, or one-time schedule; lua test job runs it immediately (About jobs).
lua push uploads, lua version create snapshots, and lua version promote makes a snapshot live or rolls back (About releases and versions).

Next steps

Handle a webhook

Sign requests with secret, verify x-lua-signature, and make handlers idempotent.

About execution contexts

What User, Data, and env resolve to in a tool, a webhook, and a job.

LuaAgent reference

Every field you can register on the agent, with types and defaults.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Marketplace

Build with AI

Examples

Build a support agent

What you’ll build

Remove the test records

What you learned

Next steps

Handle a webhook

About execution contexts

LuaAgent reference

​What you’ll build

​Remove the test records

​What you learned

​Next steps

Handle a webhook

About execution contexts

LuaAgent reference

What you’ll build

Remove the test records

What you learned

Next steps