Skip to main content

Agent function examples

Complete agent functions you can adapt. Each quoted table, column or API name, such as "orders", "orders.email" or "createTicket", is a label you insert from the editor's suggestions. When you rebuild an example, pick your own tables, columns and APIs: type " after tables.search( or apis.execute(, or "@ anywhere else. See Get suggestions.

Look up a customer's recent orders​

An agent tool with one input, email. The agent calls it when a user asks about their orders.

import { tables } from "@yellow/bot";

export default async function ({ email }) {
  const orders = await tables.search(
    "orders",
    { "orders.email": email },
    { sort: { created_at: -1 }, limit: 3 },
  );

  if (orders.length === 0) {
    return { found: false, message: "No orders found for this email address." };
  }

  return {
    found: true,
    orders: orders.map((order) => ({
      id: order.order_id,
      status: order.status,
      total: order.total,
    })),
  };
}

Save a lead without duplicates​

A Function node that checks for an existing phone number before adding a row.

import { tables } from "@yellow/bot";

export default async function ({ name, phone }, context) {
  const existing = await tables.search(
    "leads",
    { "leads.phone": phone },
    { limit: 1 },
  );
  if (existing.length > 0) {
    return { saved: false, reason: "duplicate" };
  }

  const result = await tables.insert("leads", {
    "leads.name": name,
    "leads.phone": phone,
    "leads.channel": context.source,
  });

  return { saved: result.success };
}

Create a support ticket​

Calls a ticketing API and keeps the ticket number in a global variable for later steps.

import { apis, variables } from "@yellow/bot";

export default async function ({ subject, details }, context) {
  try {
    const response = await apis.execute("createTicket", {
      subject,
      description: details,
      customerId: context.sender,
    });

    await variables.global.set({ lastTicketId: response.body.ticketId });
    return { created: true, ticketId: response.body.ticketId };
  } catch (error) {
    console.error("Ticket creation failed", error);
    return { created: false, message: "We couldn't create a ticket right now. Please try again shortly." };
  }
}

Cancel an order​

Checks the order, asks your system to cancel it, and only then updates the table.

import { apis, tables } from "@yellow/bot";

export default async function ({ orderId }) {
  const [order] = await tables.search(
    "orders",
    { "orders.order_id": orderId },
    { limit: 1 },
  );

  if (!order) {
    return { ok: false, message: "Order not found." };
  }
  if (order.status === "shipped") {
    return { ok: false, message: "This order has already shipped and can't be cancelled." };
  }

  try {
    await apis.execute("cancelOrder", { orderId });
  } catch (error) {
    console.error("Cancellation failed", error);
    return { ok: false, message: "We couldn't cancel the order. An agent will follow up." };
  }

  await tables.update("orders", {
    set:   { "orders.status": "cancelled" },
    where: [{ column: "orders.order_id", operation: "equals", value: orderId }],
  });

  return { ok: true };
}

More​