Agent Worker | AIUI | Rokid

Agent Worker 是随智能体运行的后台脚本。它适合管理多个 Page 或 Widget 打开期间共用的一份临时任务状态,或者管理只应启动一次的任务。

Agent Worker

Agent Worker 是随智能体运行的后台脚本。它适合管理多个 Page 或 Widget 打开期间共用的一份临时任务状态,或者管理只应启动一次的任务。

Agent Worker 不包含界面,也不是浏览器中的 Web Worker。它拥有独立的 JavaScript 运行环境,不提供 Page 或 Widget 的界面对象。

声明后台任务

在 app.json 的 agentWorkers 数组中声明入口:

{
  "pages": ["pages/index/index"],
  "agentWorkers": [
    {
      "name": "sync",
      "script": "workers/sync.js",
      "trigger": { "type": "open" },
      "lifetime": "foreground"
    }
  ]
}
字段类型必填说明
namestring是当前智能体内唯一且非空的任务名称
scriptstring是相对于项目根目录的 .js 或 .ts 文件路径
triggerobject是启动条件;当前仅支持 { "type": "open" }
lifetimestring是任务保持运行的方式:instant 或 foreground

script 不能使用绝对路径、URL、反斜杠或 ..。当前一个智能体只能声明一个使用 open 的 Agent Worker。

编写入口脚本

入口文件必须默认导出一个对象。每次 Page 或 Widget 成功打开时,运行时都会调用一次 onOpen(event)。

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';
  },
};

同一个正在运行的 Agent Worker 会保留 this 上的数据;后续打开 Page 或 Widget 时,仍会触发这个任务并继续使用已有状态。任务停止并重新启动后,这些数据会重新初始化;需要长期保存的数据应写入存储。

如果 onOpen() 启动了异步操作,需要在回调返回前调用 event.waitUntil(promise)。仅把 onOpen() 声明为 async 不会自动等待返回的 Promise。

避免重复启动任务

多个入口在短时间内打开时,前一次异步初始化可能尚未结束。可以保存正在执行的 Promise,让它们共用同一次初始化:

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() };
  },
};

选择运行时长

lifetime行为适合场景
instant入口脚本、onOpen() 和通过 waitUntil() 登记的任务完成后停止同步一次数据、完成一次短任务
foreground只要当前智能体仍有 Page 或 Widget 打开就继续运行共享连接、持续监听

background 是预留值,当前版本不支持;使用它会导致 app.json 校验失败。

可用能力与限制

Agent Worker 可以使用:

  • 定时器、Promise、console 和 performance
  • URL、文本编解码、Web Crypto 和 WebAssembly
  • 项目内的 ES Module

Agent Worker 不提供 Page、Widget、window、document、fetch、界面渲染、路由和媒体采集能力。需要更新界面或发送网络请求时,应由 Page 或 Widget 处理。

继续阅读

  • AgentWorker API:查看 onOpen()、waitUntil()、close() 和可用属性
  • app.json:查看应用入口配置