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/js-api/open/business/callTool.md.

callTool

调用当前应用的 Tool。

豆包会根据当前应用插件页面或会话 Widget 确定应用和版本,开发者只需传入 Tool 名称和参数。 Tool 正常结果通过 toolResult 返回,Tool 业务错误通过 toolError 返回,两者都会正常 resolve;调用前校验、鉴权或返回结构校验失败时 Promise reject。

支持版本

前端库版本不低于 0.0.42。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片支持

接入准备

前置条件

  • Android:在当前应用的应用插件页面或由当前应用真实生成的会话 Widget 内调用,且目标 Tool 已在当前应用版本中配置
  • iOS:在当前应用的应用插件页面或由当前应用真实生成的会话 Widget 内调用,且目标 Tool 已在当前应用版本中配置

使用说明

  • toolResult 与 toolError 互斥;toolError 是正常返回的 Tool 业务错误,不会导致 Promise reject。skipWidgetUpdate 为 true 时不执行 Widget 更新阶段,因此不会返回 cardUpdateError;否则 cardUpdateError 表示 Tool 已执行但当前 Widget 更新失败。reloadWidget 默认为 true,仅影响更新后的 Widget 是否重建。重试会再次执行 Tool,请避免重复触发。

调用方式

异步 API

callTool(params: CallToolParams): Promise<CallToolResult>

入参

名称类型必填默认值约束说明
reloadWidgetboolean否true-是否重新创建更新后的 Widget 组件;设为 `false` 时复用当前组件。
skipWidgetUpdateboolean否false仅影响会下发 Widget 的 Tool。是否跳过 Widget 更新阶段。设为 `true` 时,即使 Tool 下发 Widget,也只返回 Tool 数据,
不更新当前 Widget。
toolArgsRecord<string, unknown>是--Tool 入参。
toolNamestring是--当前应用内需要调用的 Tool 名称。

调用示例

import { callTool } from '@doubao-dev/framework/api';

const result = await callTool({
  toolName: 'query_order',
  toolArgs: {
    orderId: 'order-123'
  }
});

if (result.toolError) {
  console.warn(result.toolError.code, result.toolError.message);
} else {
  console.log(result.toolResult);
}

成功返回

名称类型必返说明
cardUpdateErrorCallToolError否Tool 已执行,但返回结果未能用于更新当前 Widget 时的错误。仅 Widget 场景可能返回。
cardUpdateError.codestring否错误码。
cardUpdateError.messagestring否错误信息。
cardUpdateError.phase"render"否错误阶段,固定为渲染阶段。
toolResultToolResult否Tool 正常结果,与 `toolError` 二选一。
toolResult.contentRecord<string, unknown>[]否Tool 返回的内容块。
toolResult.isErrorboolean否Tool 执行是否返回错误结果。
toolResult.structuredContentunknown否Tool 返回的结构化内容。
toolErrorCallToolBusinessError否Tool 业务错误,与 `toolResult` 二选一。该字段不会导致 API reject。
toolError.codenumber否Tool 业务错误码。
toolError.messagestring否Tool 业务错误信息。

返回示例

{
  "toolResult": {
    "content": [
      {
        "type": "text",
        "text": "订单已支付"
      }
    ],
    "structuredContent": {
      "orderId": "order-123",
      "status": "paid"
    }
  }
}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 104,
  "errMsg": "invalid parameter"
}

错误码

errNoerrMsg平台触发条件处理建议
103feature not supportAndroid、iOS在 Worker 等非应用插件页面、Widget 容器中调用仅在应用插件页面或会话 Widget 中调用。
104invalid parameterAndroid、iOStoolName 为空、toolArgs 无法序列化为 JSON 对象,或传入的 skipWidgetUpdate、reloadWidget 不是布尔值修正 Tool 名称、参数和 Widget 更新控制参数后重试。
112invalid resultAndroid、iOSTool 正常结果、业务错误或 Widget 更新错误结构无效稍后重试;持续失败时反馈 Tool 或服务端返回异常。

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

平台差异

  • 非应用插件页面、Widget 容器返回 103;参数非法返回 104;返回结构无效返回 112;上下文无效、网络或服务端调用失败返回 102。