端工具(Client Tool)开发
端工具把端侧可执行的能力暴露给 Agent。Agent 根据用户意图选择工具,宿主调用对应 handler,handler 返回真实执行结果。适合端侧计算、读取应用存储或调用公开宿主 API;需要服务端凭证的业务仍放在 Server Tool 中。
端工具没有界面,不等同于 Page 中的点击回调,也不能直接读取另一个 Page 的 React state。需要 Agent 改变已打开页面时,使用全页事件。
接入所需文件
tools.json 中写 tool_type: "client",才表示端工具;省略该字段时当前构建转换按 server 处理。声明工具不会自动实现 handler,只有源码文件也不能代替 Agent 可见的工具声明。
JSB 调用限制
端工具在独立的 ToolRuntime 中执行,可调用的 JSB 受白名单限制。当前 Android 和 iOS 允许以下业务 JSB;表中名称是宿主方法名,业务仍通过 @doubao-dev/framework/api 中对应的公开 API 调用。
工具结果回传由 Framework 处理,业务只需返回符合协议的结果对象。
不在白名单中的 JSB 会被拒绝,包括 navigateTo、redirectTo、reLaunch、navigateBack、openPage 等路由能力。SDK 导出了某个 API,或该 API 能在 Page / Widget 中使用,不代表它能在端工具中调用;需要页面跳转时,应在支持该路由能力的 Page / Widget 交互中完成。
白名单放行也不代表调用必然成功:仍需满足接口权限、用户授权、宿主支持和限流等条件。在 tools.json 中声明 permissions 不能扩大端工具的 JSB 白名单;业务需要处理实际调用失败。
实现一个最小端工具
以下示例在端侧计算整数分金额。它只演示计算,不会创建订单或扣款。前提是已有可运行的应用插件项目和 src/app.ts。
声明工具
在项目根目录 tools.json 中加入:
inputSchema 和 outputSchema 本身都必须是 JSON 对象。这里 outputSchema.type 为 object;绑定卡片时则需要描述对象数组,见下文。Schema 描述不替代 handler 的运行时校验。
字段说明:
这里使用的是平台支持的 JSON Schema 子集,不支持 enum、数值上下界(minimum / maximum,即 min/max)等校验能力。不要在 schema 中添加这些约束;将可选值和取值范围写入字段 description,并在业务代码中校验。此限制同时适用于 tools.json 的 inputSchema、outputSchema 和 events.json 的 payloadSchema。
注册入口
将以下 tools 配置合入已有 src/app.config.ts,保留现有 Page / Widget 配置:
entry 相对于 src/,不写 .ts 后缀。显式 name 必须与 tools.json 的 name 一致;省略 name 时默认使用入口目录名。仅靠扫描 src/tools/ 不能替代 app.config.ts.tools 注册。
编写 handler
创建 src/tools/calculate-total/index.ts:
handler 接收已经解析的对象,不需要 JSON.parse(input);可以返回结果对象或 Promise。端工具使用默认导出的函数。
当前返回值必须包含 content 数组,其中每个块为 { type: 'text', text: string };structuredContent 可为对象或对象数组。预期的业务失败可以返回 isError: true 和可恢复的文本说明;抛错或返回不合法结果会作为调用失败反馈。不要返回一个字符串代替整个结果对象。
可选:让工具结果展示为卡片
在最小例子通过后再接入卡片。需要同时修改三个位置:
- 在
app.config.ts.widgets注册 Widget,使用稳定id,例如AmountCard;需要 Web 预览时设置web: true。 - 在该工具声明中加入
_meta: { "ui": { "widgetId": "AmountCard" } },把outputSchema改为下列对象数组 schema。 - 把成功返回的
structuredContent改为对应实体数组;错误分支仍返回isError: true,不伪造成功实体。
成功结果中的数组可写为:
这里用计算输入组成演示标识;真实业务应使用领域内稳定的实体 ID。Widget 按单个实体读取 View Data,例如 useViewData<{ calculation_id: string; total_cents: number }>()。Widget 入口和完整实现方式见卡片开发。
不要在 schema 中声明保留字段 entity_type。当前运行时为成功返回的实体数组补充 entity_type: <tool name>,构建工具生成对应的实体和卡片绑定配置。
验证与排障
找不到工具时,检查 tool_type、tools.json.name、app.config.ts.tools[].name 和入口文件;提示 handler 必须为函数时检查默认导出;提示 MCP result 不合法时检查 content 和 structuredContent。Web 工具调试的入口、结果面板和真机验收边界见本地调试与预览。
运行时隔离、输入解析与错误处理的完整说明见端工具、事件与页面上下文。