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/client-framework/agent-interaction.md.

Agent 与端侧交互

本文说明 Agent 与端侧协作时的执行主体、数据方向和生命周期。完整接入示例见端工具开发和全页开发。

两条独立链路

能力数据流向入口与执行主体成功证据
Client ToolAgent → 宿主 → handler → Tool Resultapp.config.ts.tools 注册的默认函数在端工具运行时执行调用记录、真实返回值,绑定卡片时还需检查实体与渲染
Agent EventAgent → 宿主 → App → 页面订阅者Framework 接收事件,调用可选 onAgentEvent 并分发到 useAgentEvent事件记录、订阅回调、页面状态变化

图中的两条路径分别验证。工具结果不会自动更新已打开页面;页面事件也不会自动回传 Tool Result。

端工具运行时

Kit 从 app.config.ts.tools 收集入口,生成端工具注册和启动代码;业务不手动调用 bootstrap。端工具产物与 App、Page / Widget 入口分开,不能依赖另一入口的模块变量、组件 state 或生命周期已经执行。

handler 必须默认导出函数,签名为 (input: Record<string, unknown>) => unknown | Promise<unknown>。Framework 对输入执行以下规范化:

  • 缺省输入变为 {};
  • 对象输入直接传给 handler;
  • JSON 字符串先解析为对象;非对象或解析失败按调用错误处理;

业务始终按对象接收,再校验字段及业务约束。调用只向 handler 传入这一个对象参数。

返回值需要满足当前端工具结果契约:

interface ClientToolResult {
  content: { type: 'text'; text: string }[];
  structuredContent?: Record<string, unknown> | Record<string, unknown>[];
  isError?: boolean;
  _meta?: Record<string, unknown>;
}

content 必须存在,目前仅支持文本块。运行时检查结果外形,不替代对 outputSchema 和业务数据的完整校验。成功的实体数组会逐项补充 entity_type: <tool name>;对象形式的 structuredContent 不做该补充。

返回 isError: true 表示业务失败;handler 抛错、返回不合法结果或工具不存在,则通过宿主调用结果反馈错误。不要假设端工具错误一定进入 Page 的 useError 或 App 的生命周期回调。

端工具使用函数默认导出。调用宿主能力前,先确认端工具 JSB 白名单。端工具不能使用白名单之外的 JSB,包括路由能力;声明权限不能扩大白名单,已放行的接口仍需满足授权、宿主支持和限流条件。需要页面当前状态时,使用事先约定的数据通信方式。

事件接收与订阅生命周期

events.json 描述可发出的业务事件,Skill 中的 {{event:<name>}} 暴露对应事件。模型生成事件后,由宿主投递;Framework 的接收顺序是:

  1. 如果 App 定义了 onAgentEvent(name, payload),调用它;
  2. 将 payload 分发到应用事件通道中对应的业务事件;
  3. useAgentEvent(name, callback) 的订阅者执行回调,由业务更新状态;

未定义 App 回调不影响订阅分发。手动重复转发会造成重复处理。App 回调适合应用级处理或观察;页面回调适合更新当前页面展示。

Hook 通过 Effect 注册订阅,事件名变化或组件卸载时取消旧订阅,并使用最近一次渲染的 callback。它不按页面栈顶、业务 ID 或可见性筛选,也不存储和重放历史 payload。因此:

  • 先打开并挂载页面,再发送更新事件;
  • 使用业务对象或任务标识检查目标归属;一个任务有多个实例时进一步区分实例;
  • 隐藏但仍挂载的页面可能继续收到事件,必要时结合显示与隐藏生命周期限制处理;
  • 重复投递不能重复扣款、提交订单或累加状态;需要此类操作时使用具有业务幂等性的服务接口;
  • 重建页面时从可信数据源恢复状态,不依赖错过的事件;

payload 类型是 Record<string, unknown>。同步回调错误由事件通道交给 App 错误处理,不阻断其他监听器;异步请求应自行捕获 rejection,并处理页面销毁或请求过期。