For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/frontend-development/conversation-js-api.md.

对话相关 JS API 使用与权限声明

卡片、页面或 Worker 可以通过 @doubao-dev/framework/api 调用宿主开放能力。下表同时标注当前已公开能力和正在建设的能力;建设中的能力不可按现有 SDK API 使用。

核心 API 一览

API用途典型场景
callTool(name, args)(建设中)组件直接触发 MCP 工具调用,并使用工具结果更新当前交互用户点击「加入购物车」后调用对应工具,再根据结果刷新卡片
sendFollowUpMessage({ content })以用户身份发送后续消息,触发新一轮对话、API 调用或引导模型响应用户选择「拿铁」后,把选择结果和响应建议发送给宿主
updateModelContext({ taskId?, entityId?, content })在任务或实体维度向 Agent 补充上下文,不触发新一轮对话用户修改配送方式后,把最新选择同步给 Agent,供后续推理使用
updateWidget({ widgetId?, widgetData })更新指定 Widget 实例的渲染数据,也可切换到另一个已注册的 Widget卡片操作完成或服务端返回新结果后,持久化刷新原卡片

选型建议

  • 需要直接调用 MCP 工具:规划使用 callTool;该能力仍在建设中,当前 SDK 仓库尚未公开导出,不能在现有业务代码中调用。
  • 需要继续会话、请求宿主发起 API 调用或引导模型响应:使用 sendFollowUpMessage。content 是消息数组,支持 text、api/call 和 responseHint 三种内容。
  • 只需要补充 Agent 后续推理所需的业务状态:使用 updateModelContext。content 必填,taskId 和 entityId 可选。

调用示例

import { sendFollowUpMessage, updateModelContext, updateWidget } from '@doubao-dev/framework/api';

await sendFollowUpMessage({
  content: [{ type: 'text', text: '选择拿铁' }]
});

await updateModelContext({
  entityId: 'order-001',
  content: '用户选择了标准配送'
});

await updateWidget({
  widgetData: JSON.stringify({ status: 'done' })
});

权限与运行环境

  • updateModelContext 和 updateWidget 的公开契约标明:Android、iOS 无需预先申请应用 scope 或系统权限;PC、HarmonyOS 暂未提供实现。
  • sendFollowUpMessage 可在 Widget、应用插件页面或 Worker 中调用。宿主会根据调用位置关联对应会话;当前源码没有声明额外的权限契约,不应据此推断其他平台支持情况。