AgentWorker | AIUI | Rokid

AgentWorker is a background-task instance created by the runtime. Fields and methods from the entry module's default-exported object are copied onto this instance, which …

AgentWorker

AgentWorker is a background-task instance created by the runtime. Fields and methods from the entry module's default-exported object are copied onto this instance, which becomes this when onOpen(event) runs.

Keep Shared State for the Current Task

Place reusable data and methods directly on the default-exported object:

export default {
  openCount: 0,
  status: null,

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

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

These fields remain available while the current Agent Worker is running. A new instance is created after the task stops and starts again, so this is not permanent storage.

Wait for Asynchronous Work

The return value from onOpen() is ignored. To track asynchronous work, call event.waitUntil() before onOpen() returns:

export default {
  onOpen(event) {
    event.waitUntil(this.synchronize());
  },
  async synchronize() {
    await new Promise((resolve) => setTimeout(resolve, 100));
  },
};

waitUntil() accepts a Promise, but the call itself must happen during the synchronous execution of onOpen(). Calling it later throws InvalidStateError.

Stop the Background Task

Call this.close() to request that the current Agent Worker stop:

export default {
  openCount: 0,
  onOpen() {
    this.openCount += 1;
    if (this.openCount >= 3) {
      this.close();
      return;
    }
  },
};

The stop request does not interrupt the current function immediately. Return after calling it instead of starting more work.

Use the Global Event Style

Instead of the default export's onOpen(), you can listen for open on the global object:

self.addEventListener('open', (event) => {
  event.waitUntil(new Promise((resolve) => setTimeout(resolve, 100)));
});

The AgentWorker instance is not an EventTarget; use self when you need addEventListener(). The default export's onOpen() is usually more convenient when state is stored on this.

Current Behavior

  • AgentWorker is created by the runtime and cannot be constructed with new AgentWorker().
  • name, navigator, and close are reserved. Fields with those names in the default export do not replace them.
  • this.navigator and the global navigator are the same object.
  • Global self and globalThis refer to the Agent Worker global object, not the this value used by onOpen().
  • Every open trigger calls onOpen(); overlapping asynchronous work is not merged automatically.
  • Agent Workers do not provide fetch; start network requests from a Page or Widget.

For declarations and lifetime configuration, see Agent Worker Development.

API Reference

AgentWorker

MemberTypeDescription
namestringAgent Worker name declared in app.json
navigatorWorkerNavigatorEnvironment information and extra features available to the task
close()functionRequests that the current Agent Worker stop
Custom fields and methodsanyMembers copied from the entry module's default-exported object

onOpen(event)

Runs once each time the agent opens successfully. If the entry module is still loading, events are queued and delivered in order after loading completes.

ParameterTypeDescription
eventExtendableEventThe current open event; use waitUntil() to register a Promise that must finish

The return value is ignored.

ExtendableEvent

ExtendableEvent extends the standard Event with this method:

MethodDescription
waitUntil(value)Waits for Promise.resolve(value); must be called during synchronous event delivery

The event's type is 'open'. Its target and currentTarget refer to the Agent Worker global object.

WorkerNavigator

PropertyTypeDescription
idstringContent identifier for the current agent
renderingEnabledbooleanWhether the entry that started this task can display an interface
versionsNavigatorVersionsAIUI runtime version information
userAgentstringCurrent runtime identification string
languagestringPreferred language
languagesstring[]Language preferences in priority order
regionstringCurrent region information

AgentWorkerGlobalScope

Global self, globalThis, and name live on AgentWorkerGlobalScope. It extends EventTarget and supports:

self.addEventListener('open', listener);
self.removeEventListener('open', listener);
close();