Agent 会话 | AIUI | Rokid

通过 getApp().getAgent() 向当前 Agent 会话发布背景数据、发送用户消息、展示可更新的卡片,以及调用远端工具和读取资源。它不会创建模型或新对话。

Agent 会话

通过 getApp().getAgent() 向当前 Agent 会话发布背景数据、发送用户消息、展示可更新的卡片,以及调用远端工具和读取资源。它不会创建模型或新对话。

发送用户消息

在 App 或 Page 的业务方法中发送文本消息。操作成功表示会话确认接收,不代表模型已经回复:

async function askAboutProduct() {
  const agent = getApp().getAgent();
  try {
    await agent.conversation.sendMessage({
      role: 'user',
      content: [{ type: 'text', text: '请介绍商品 DEMO。' }],
    });
  } catch (error) {
    console.error(error.name, error.message);
  }
}

先读取 agent.capabilities.operations 可以判断当前会话支持的操作。例如,发送文本消息对应 conversation.sendMessage,同时要求 capabilities.contentTypes 包含 text。能力可能在连接过程中变化;请求本身仍应处理失败。

显式发布和移除上下文

应用状态和日志不会自动成为模型输入。把需要的背景数据发布为上下文条目,并保留返回的句柄:

const agent = getApp().getAgent();
const selection = await agent.provideContext({
  key: 'selection',
  description: 'The product selected by the user',
  value: { selectedSku: 'DEMO' },
});

// 用户改选商品时替换这一条的值:
await selection.update({ selectedSku: 'SKU-002' });

// 业务结束时移除:
selection.dispose();

发布和更新不会发送用户消息或自动开始推理;成功只表示确认接收,不保证模型已经读取。多个条目汇总发布,更新按顺序发送。条目是模型只读背景,不是双向共享状态。

发送和更新卡片

使用 sendCard() 可以在 Rokid AI App 的会话中展示一张卡片。例如,智能体可以发送一张商品卡片,让用户点击后打开商品页面。目前卡片支持标题和跳转链接;描述和 data 的展示将在后续支持。

在 App 或 Page 的业务方法中调用:

async function sendProductCard() {
  const conversation = getApp().getAgent().conversation;
  try {
    const card = await conversation.sendCard({
      title: '查看商品 DEMO',
      href: 'https://example.com/products/DEMO',
    });
    return card;
  } catch (error) {
    console.error('发送卡片失败', error);
  }
}

title 是用户看到的标题,href 是点击卡片后打开的地址。部分运行时版本尚不支持 href,传入时会返回 DataError。

调用成功后会返回卡片句柄,可以用它更新卡片:

const card = await sendProductCard();
if (card) {
  await card.update({
    title: '查看更新后的商品',
    href: 'https://example.com/products/DEMO',
  });
}

更新会替换整张卡片,因此需要重新提供要保留的字段。每次 sendCard() 都会新建一张卡片,目前没有删除接口。卡片内容不会自动提供给模型;如果模型也需要这些信息,请另外调用 provideContext()。

使用远端工具和资源

远端工具名称和参数以当前服务提供的契约为准。下面假定服务已提供 check_stock:

const agent = getApp().getAgent();
const result = await agent.callTool('check_stock', { sku: 'DEMO' });
if (result.isError) {
  console.error(result.content);
} else {
  console.log(result.structuredContent ?? result.content);
}

const page = await agent.listResources();
const resource = page.resources[0];
if (resource) console.log(await agent.readResource(resource.uri));

isError 是工具返回的业务失败,Promise 仍会完成;连接、授权和协议失败会拒绝。page.nextCursor 存在时,用 listResources({ cursor: page.nextCursor }) 继续读取。资源内容可能是文本或 base64 二进制,不应当作脚本执行。

连接与生命周期

  • 只在 App/Page 中使用。独立 Agent Worker 不提供 getAgent()。
  • 每次业务流程开始时获取当前会话。连接重建后,旧会话、上下文条目和卡片句柄失效;不会自动把旧数据发布到新连接。
  • 请求会等待连接就绪。默认超时 30 秒,包含排队和等待连接的时间;取消和超时无法撤回已经处理的写入。会修改数据的操作不要自动重试。
  • 页面不再需要上下文时主动 dispose(),或用 lifetime 绑定生命周期。导航不会自动删除已发送卡片;卡片可能在 App 退出后继续保留在会话中,但旧句柄不再可用。
  • 会话不能读取整个对话,也不会修改 LanguageModelSession 的私有历史。JSON payload 上限 1 MiB,最多 128 个待完成请求。

API Reference

App

getAgent()

返回当前 AgentSession。获取句柄不开始推理,也不创建新对话。

environment

只读、独立的公开环境对象,详见下方 Environment;内容不会自动发布给模型。

AgentSession

connectionState

只读状态:unavailable(无服务)、connecting(连接中)、ready(可用)、closed(旧会话关闭)。

capabilities

只读快照,包含 operations、contentTypes,以及表示列表变更通知是否可用的 toolListChanged 和 resourceListChanged。

invocation

只读的最新调用信息或 null。包含 invocationId、revision 和区分输入、部分输入、结果或取消的 type。部分输入不是完整或已校验的参数。

conversation

只读的消息与卡片操作对象,提供下述发送方法。

provideContext(source, options?)

返回 Promise<ContextEntry>。同会话最多 128 条上下文;重复 key 以 InvalidStateError 拒绝。需要 conversation.updateContext 能力。

字段类型必填说明
source.keystring是1–128 个字母、数字、下划线、点或连字符;会话内唯一。
source.descriptionstring是不得全为空白的说明。
source.valueJSON 值是显式提供给模型的背景数据。
options.lifetimeAbortSignal否中止时自动移除条目;与请求 signal 分开。

options 还接受下方通用请求选项。

callTool(name, input, options?)

返回 Promise<ToolResult>;需要 tools.call 能力。name 是远端工具名,input 是 JSON 对象。结果含 content(文本条目数组),以及可选 structuredContent、isError、uiMetadata;uiMetadata 仅供界面使用。除通用请求选项外,可用 options.onProgress(progress) 接收 value、可选 total 和 message。

listResources(options?)

返回 Promise<{ resources, nextCursor? }>;需要 resources.list 能力。选项除通用字段外还接受 cursor: string。资源项含 uri、name 及可选 description、mimeType。

readResource(uri, options?)

返回 Promise<ResourceContent[]>;需要 resources.read 能力。每项含 uri、可选 mimeType,以及二选一的 text 或 base64 blob。

connectionstatechange

连接状态改变时触发,新的状态在只读 event.detail 中。

capabilitieschange

能力快照改变时触发,新的能力在 event.detail 中。

toolinput

收到完整调用输入时触发,event.detail 包含调用信息和 input。

toolinputpartial

收到部分输入时触发,event.detail 不应作为已完成的业务参数执行。

toolresult

收到调用结果时触发,结果在 event.detail.result 中。

toolcancelled

收到调用取消信息时触发,event.detail 可含 reason。

toolschange

远端工具列表变化通知;是否提供此通知见 capabilities.toolListChanged。

resourceschange

远端资源列表变化通知;是否提供此通知见 capabilities.resourceListChanged。

Conversation

sendMessage(message, options?)

返回 Promise<void>,需要 conversation.sendMessage 和文本内容能力。目前 message 仅支持 { role: 'user', content: [{ type: 'text', text: string }] };完成表示确认处理,不表示推理已完成。

sendCard(definition, options?)

返回 Promise<CardHandle>,需要 conversation.sendCard。卡片定义与更新共用以下字段;通用请求选项不支持卡片 lifetime。

字段类型必填说明
titlestring是卡片标题,必须包含非空白文本。
hrefstring否点击卡片后打开的地址;部分运行时版本尚不支持,传入会返回 DataError。
descriptionstring否卡片描述;展示将在后续支持。
dataJSON 对象否可选的卡片数据;展示将在后续支持。

ContextEntry

update(value, options?)

返回 Promise<void>,完整替换该条目的 JSON 值,其他条目不变。支持通用请求选项。

dispose()

返回 undefined,立即移除本地条目并安排发布剩余条目;没有可等待的确认结果。移除最后一条会清空发布内容。

CardHandle

id

只读、由运行时生成的卡片标识,限定在所属连接和 App 内。

update(definition, options?)

返回 Promise<void>,需要 conversation.updateCard。保留 id 并完整替换展示数据;完成表示确认处理,不保证画面已显示。

通用请求选项与错误

字段类型默认值说明
signalAbortSignal无取消单次请求,不移除已发送卡片或已建立的上下文。
timeoutMsnumber300001–120000 毫秒,包含等待连接和排队时间。

不支持的操作以 NotSupportedError 拒绝,关闭的会话以 InvalidStateError 拒绝。其他错误包括 NotAllowedError、AbortError、TimeoutError、NetworkError、DataError、QuotaExceededError。

Environment

theme

可选、只读的环境主题名称;读取不会修改渲染主题。

locale

可选、只读的环境语言;不修改 navigator.language。

displayMode

可选、只读的当前显示模式名称。

availableDisplayModes

可选、只读的可用显示模式名称数组;不要直接修改。

safeAreaInsets

可选、只读的 { top, right, bottom, left } 安全区域边距快照。

change

环境更新时触发,event.detail 是新快照。通过 getApp().environment.addEventListener('change', listener) 监听。