Task Variables and Templates

Figranium tasks accept typed variables and reference them inside action values with a {$name} template. The SDK ships a variable() helper that produces the correct token, plus typed shapes for declaring variables on a Task.

Declare task variables

Task variables live under task.variables. Each entry has a type and a default value.

import type { Task } from "@figranium/sdk";

const task: Task = {
  name: "Search",
  url: "https://example.com",
  mode: "agent",
  variables: {
    query: { type: "string", value: "figranium" },
    limit: { type: "number", value: 10 },
    strict: { type: "boolean", value: true },
  },
  actions: [
    /* ... */
  ],
};

VariableType is "string" | "number" | "boolean". Additional fields are allowed on each variable entry, and unknown fields are preserved by the SDK’s flexible task type.

Reference variables in actions

Anywhere an action expects a string value, use variable(name) to reference a task variable. The helper returns {$name}.

import { actions, variable } from "@figranium/sdk";

actions.type("#search", variable("query"));
actions.set("activeQuery", variable("query"));
actions.request("https://api.example.com/search", {
  method: "POST",
  body: JSON.stringify({ q: variable("query") }),
});

variable("") throws a TypeError; names must not be empty.

Override at runtime

Pass variables when executing a task to override the defaults for a single run. Runtime variables use plain values, not the typed shape used at declaration time.

const result = await figranium.runTask(task.id!, {
  variables: {
    query: "browser automation",
    limit: 25,
  },
});

You can also pass taskVariables, which sets task-scoped defaults for the run without changing the saved task.

await figranium.runTask(task.id!, {
  variables: { query: "figranium" },
  taskVariables: { userAgent: "custom" },
});

Direct execution

scrape, agent, and headful accept the same runtime variable shape when called directly:

await figranium.scrape({
  url: "https://example.com",
  variables: { query: "figranium" },
});

See Execution resource for full input shapes.

Auto-created variables

Some server-side flows auto-create variables (for example when a script writes a result to a new name). Those entries include autoCreated: true. The SDK preserves the flag on read and write.

Use variable() for every template reference so your code stays type-safe and refactorable. Hard-coding {$name} strings is brittle when variable names change.

Actions

Every action helper that accepts a template value.

Tasks resource

Full reference for saving and running tasks.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

Task Variables and Templates

Declare task variables

Reference variables in actions

Override at runtime

Direct execution

Auto-created variables

Actions

Tasks resource

​Declare task variables

​Reference variables in actions

​Override at runtime

​Direct execution

​Auto-created variables

​Related

Actions

Tasks resource

Declare task variables

Reference variables in actions

Override at runtime

Direct execution

Auto-created variables

Related