Agent Worker | AIUI | Rokid

An Agent Worker is a background script that runs with an agent. Use it to manage one temporary task state while several Pages or Widgets are open, or for work that should…

Agent Worker

An Agent Worker is a background script that runs with an agent. Use it to manage one temporary task state while several Pages or Widgets are open, or for work that should start only once.

An Agent Worker has no interface and is not a browser Web Worker. It has an independent JavaScript environment and does not expose Page or Widget interface objects.

Declare a Background Task

Declare the entry in the agentWorkers array in app.json:

{
  "pages": ["pages/index/index"],
  "agentWorkers": [
    {
      "name": "sync",
      "script": "workers/sync.js",
      "trigger": { "type": "open" },
      "lifetime": "foreground"
    }
  ]
}
FieldTypeRequiredDescription
namestringYesA non-empty task name that is unique within the agent
scriptstringYesA .js or .ts path relative to the project root
triggerobjectYesWhen to start the task; currently only { "type": "open" } is supported
lifetimestringYesHow long the task stays active: instant or foreground

script cannot use an absolute path, URL, backslash, or ... An agent can currently declare only one Agent Worker with the open trigger.

Write the Entry Script

The entry file must default-export an object. The runtime calls onOpen(event) each time a Page or Widget opens successfully.

export default {
  openCount: 0,

  onOpen(event) {
    this.openCount += 1;
    event.waitUntil(this.refresh());
  },

  async refresh() {
    await new Promise((resolve) => setTimeout(resolve, 100));
    this.latestStatus = 'ready';
  },
};

The same running Agent Worker keeps values stored on this. Opening another Page or Widget triggers the same task and continues with its existing state. Those values are reset after the task stops and starts again; use storage for data that must persist.

When onOpen() starts asynchronous work, call event.waitUntil(promise) before the callback returns. Declaring onOpen() as async does not automatically track its returned Promise.

Avoid Starting the Same Work Twice

When several entries open close together, an earlier asynchronous setup may still be running. Store the active Promise so they can share the same setup:

export default {
  service: null,
  startPromise: null,

  onOpen(event) {
    event.waitUntil(this.ensureService());
  },

  ensureService() {
    if (this.service) return Promise.resolve(this.service);

    if (!this.startPromise) {
      this.startPromise = this.createService()
        .then((service) => {
          this.service = service;
          return service;
        })
        .finally(() => {
          this.startPromise = null;
        });
    }
    return this.startPromise;
  },

  async createService() {
    return { startedAt: Date.now() };
  },
};

Choose How Long It Runs

lifetimeBehaviorTypical use
instantStops after the entry script, onOpen(), and work registered with waitUntil() finishSynchronize data or complete one short task
foregroundKeeps running while the current agent has an open Page or WidgetShared connections and continuous listeners

background is reserved and is not supported in the current release; using it fails app.json validation.

Available Features and Limits

An Agent Worker can use:

  • timers, Promises, console, and performance
  • URL, text encoding, Web Crypto, and WebAssembly
  • ES Modules from the project

An Agent Worker does not provide Page, Widget, window, document, fetch, interface rendering, routing, or media capture features. Let a Page or Widget handle visible interface updates and network requests.

Continue Reading

  • AgentWorker API: inspect onOpen(), waitUntil(), close(), and available properties
  • app.json: configure application entries