> 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.

# callTool

调用当前应用的 Tool。

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

## 支持版本

前端库版本不低于 `0.0.42`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>支持</td></tr>
</tbody>
</table>

## 接入准备

### 前置条件

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

## 使用说明

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

## 调用方式

### 异步 API

```typescript
callTool(params: CallToolParams): Promise<CallToolResult>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>reloadWidget</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否重新创建更新后的 Widget 组件；设为 `false` 时复用当前组件。</td></tr>
<tr><td><code>skipWidgetUpdate</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>仅影响会下发 Widget 的 Tool。</td><td>是否跳过 Widget 更新阶段。设为 `true` 时，即使 Tool 下发 Widget，也只返回 Tool 数据，<br>不更新当前 Widget。</td></tr>
<tr><td><code>toolArgs</code></td><td><code>Record&lt;string, unknown&gt;</code></td><td>是</td><td>-</td><td>-</td><td>Tool 入参。</td></tr>
<tr><td><code>toolName</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>当前应用内需要调用的 Tool 名称。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
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);
}
```

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>cardUpdateError</code></td><td><code>CallToolError</code></td><td>否</td><td>Tool 已执行，但返回结果未能用于更新当前 Widget 时的错误。仅 Widget 场景可能返回。</td></tr>
<tr><td><code>cardUpdateError.code</code></td><td><code>string</code></td><td>否</td><td>错误码。</td></tr>
<tr><td><code>cardUpdateError.message</code></td><td><code>string</code></td><td>否</td><td>错误信息。</td></tr>
<tr><td><code>cardUpdateError.phase</code></td><td><code>&quot;render&quot;</code></td><td>否</td><td>错误阶段，固定为渲染阶段。</td></tr>
<tr><td><code>toolResult</code></td><td><code>ToolResult</code></td><td>否</td><td>Tool 正常结果，与 `toolError` 二选一。</td></tr>
<tr><td><code>toolResult.content</code></td><td><code>Record&lt;string, unknown&gt;[]</code></td><td>否</td><td>Tool 返回的内容块。</td></tr>
<tr><td><code>toolResult.isError</code></td><td><code>boolean</code></td><td>否</td><td>Tool 执行是否返回错误结果。</td></tr>
<tr><td><code>toolResult.structuredContent</code></td><td><code>unknown</code></td><td>否</td><td>Tool 返回的结构化内容。</td></tr>
<tr><td><code>toolError</code></td><td><code>CallToolBusinessError</code></td><td>否</td><td>Tool 业务错误，与 `toolResult` 二选一。该字段不会导致 API reject。</td></tr>
<tr><td><code>toolError.code</code></td><td><code>number</code></td><td>否</td><td>Tool 业务错误码。</td></tr>
<tr><td><code>toolError.message</code></td><td><code>string</code></td><td>否</td><td>Tool 业务错误信息。</td></tr>
</tbody>
</table>

### 返回示例

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

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

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

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>在 Worker 等非应用插件页面、Widget 容器中调用</td><td>仅在应用插件页面或会话 Widget 中调用。</td></tr>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>toolName 为空、toolArgs 无法序列化为 JSON 对象，或传入的 skipWidgetUpdate、reloadWidget 不是布尔值</td><td>修正 Tool 名称、参数和 Widget 更新控制参数后重试。</td></tr>
<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android、iOS</td><td>Tool 正常结果、业务错误或 Widget 更新错误结构无效</td><td>稍后重试；持续失败时反馈 Tool 或服务端返回异常。</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

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