Use global variables in agent functions

Global variables hold information the rest of the conversation can use, such as the customer's tier, their language, or the last order they asked about. An agent function can read them to make decisions, and update them so that later steps (other agents, flows or functions) can use what it found.

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

The variables must already exist in your agent's global variables. The editor suggests the available names as you type.

Changes are saved only after the function finishes

variables.global.set doesn't save a value straight away. All updates are saved together once the function has finished running successfully. If the function fails, none of them are saved. See When changes are saved.

variables.global.get

Reads one or more global variables.

variables.global.get([name, …])   // → { name: value, … }

Parameter	Description
names	A list of variable names to read. Required.

It returns an object with an entry for each variable that has a value. A variable with no value is left out, so reading it gives undefined.

const { tier, language } = await variables.global.get(["tier", "language"]);

if (tier === "gold") {
  // offer priority support
}

variables.global.set

Updates one or more global variables.

variables.global.set({ name: value, … })

Parameter	Description
updates	Variable names and their new values. Values can be text, numbers, true/false, lists or objects. Required.

await variables.global.set({
  lastOrderId: orderId,
  orderStatus: "shipped",
});

Include only the variables you want to change. The others keep their values.

When changes are saved

Updates from set are held back until the function finishes successfully, then saved together.

• If the function fails, nothing is saved. A function that stops halfway never leaves some variables updated and others not.
• get returns the value from the start of the run. If you call set and then get for the same variable in one run, you get the old value. Keep the new value in a constant if you need it again.
• A test run never saves. The Run button lists the updates under Variable updates so you can check them, but doesn't change your variables.

Example: remember the customer between steps

This function looks up a customer once, saves their details to global variables, and skips the lookup when they're already known.

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

export default async function ({ phone }) {
  const { customerName, customerTier } = await variables.global.get([
    "customerName",
    "customerTier",
  ]);

  // Already identified earlier in the conversation
  if (customerName) {
    return { name: customerName, tier: customerTier };
  }

  const [customer] = await tables.search(
    "customers",
    { "customers.phone": phone },
    { limit: 1 },
  );
  if (!customer) {
    return { name: null, tier: null };
  }

  await variables.global.set({
    customerName: customer.name,
    customerTier: customer.tier,
  });

  return { name: customer.name, tier: customer.tier };
}

Things to know

• Write the names directly in your code, as in get(["tier"]) or set({ tier: "gold" }). The names a function uses are detected when you save it, and only those are made available when it runs. A name held in another variable, as in get([name]), isn't detected and comes back undefined.
• For agents, shared memory (agentic flows) must be on. If it's off, get returns nothing for every variable and set has no effect. Functions follow the same rule as workflows.
• Use variables for small values such as IDs, names and statuses. Keep larger or long-lived data in a database table.