---
title: 工具资源体系
description: 区分平台内建工具、可复用工具资源、使用绑定和运行时状态。
icon: wrench
---

# 工具资源体系

工具配置分成三层。每一层只保存自己负责的信息，避免同一个工具在不同 Assistant 中无法复用。

| 层级 | API 字段 | 负责内容 | 例子 |
| --- | --- | --- | --- |
| 平台内建工具 | `builtInTools` | 与对话运行时紧密绑定的能力 | 结束对话、更新状态、跳过本轮、转接人工 |
| 工具资源 | `Tool` | 可复用的连接、请求/响应结构和工具私密 | HTTP、MCP、Client Tool |
| 工具绑定 | `toolBindings` / `toolBinding` | 某次使用中的参数来源、模板输入和结果映射 | `order_id` 由模型填写，`tenant` 来自变量 |

提示词 Pipeline 的长任务通过独立的[任务后端资源](/prompt-task-backends)配置，可选内置 Reasoner 或外部 OpenCode。OpenCode 不属于工具资源；Speaker 的 `delegate_task` 等任务控制入口由平台自动注册，无需管理员填写函数名。Reasoner 只使用后端资源显式绑定的 HTTP/MCP 工具。

## 平台内建工具

内建工具不是“组件库 / 工具资源”中的记录，也没有 `toolId`。Prompt 在 Assistant 层配置，Workflow 可在全局或独立 Agent 阶段配置。

```json
{
  "builtInTools": {
    "endConversation": {
      "description": "用户告别或任务完成时结束对话",
      "messageType": "none",
      "customMessage": "",
      "captureReason": true,
      "allowEndInterruption": false
    }
  }
}
```

`updateState` 可像 ElevenLabs Update State 一样修改已声明的动态变量。每条规则使用显式表达式，可由 `constant`、`variable`、`llm`、`if`、布尔/比较/算术节点组成。内建 `updateState` 允许 `llm` 叶子；Workflow 的确定性 Update State 节点复用同一表达式结构，但不允许 `llm` 叶子。

## 可复用工具资源

资源只保存所有使用者共享的内容：

- HTTP：URL、method、headers、body 结构、参数 schema。
- MCP：Server 引用、远端工具名和 input schema。
- Client Tool：客户端函数名、参数 schema 和等待策略。
- Secrets：仅在该资源执行时注入 HTTP Header，必须使用 `secret__` 前缀，不注册成全局对话变量。

需要不同 Assistant 提供不同值的占位符使用 `{{input__name}}`。资源声明 `templateInputs`，具体值由绑定提供。

## 工具绑定

```json
{
  "toolId": "tool_query_order",
  "argumentBindings": {
    "order_id": { "source": "model" },
    "tenant": { "source": "variable", "variableName": "tenant_id" }
  },
  "templateBindings": {
    "region": { "source": "literal", "value": "cn" }
  },
  "resultAssignments": {
    "order_status": "status"
  }
}
```

参数来源有四种：

- `model`：暴露给 LLM，由模型在调用时填写。
- `variable`：读取已声明的动态变量或平台 `system__*` 变量。
- `literal`：绑定中的固定值。
- `template`：绑定中的模板值，可在执行时渲染普通动态变量。

Startup Action 和 Workflow Action 是确定性调用，不允许 `model` 来源。`resultAssignments` 的目标必须是已声明的动态变量。不等待响应的 Client Tool 不能配置结果映射。

## 动态变量还是 Client Tool

选择标准是“状态存在哪里”：

- 如果只是改变对话中的业务状态，使用内建 `updateState`。
- 如果需要立即操作浏览器 UI、设备或宿主应用，使用 Client Tool。

因此 `set_photo_button_visible` 在当前语义下保持 Client Tool：它是对浏览器按钮的命令式副作用，不是只更新后端会话状态。如果未来 UI 完全以服务端状态声明式渲染，可改为更新 `photo_button_visible` 变量，由客户端订阅状态事件。

Client Tool 连接时会上报支持的函数名。当前客户端未上报某个函数时，Broker 在调用前立即返回错误，不等待超时。

## 版本边界

Tool Resource v4 是一次性迁移：公开 Workflow 写入接口只接受 `specVersion: 4`。数据库迁移会同时迁移 Prompt 和 Workflow，并删除原 System 工具资源。回滚该迁移需要使用部署前备份。

## Prompt Realtime 能力边界

Prompt Realtime 不再用运行模式做统一禁用，而是读取所选 Realtime 接口的 `fieldSchema.features.realtimePromptTools` 能力声明：

- Qwen Audio Realtime 支持 HTTP、MCP、Client Tool，以及 `endConversation`、`updateState`、`requestHumanHandoff`。
- `skipTurn` 只在 Pipeline 开放。端到端音频模型在工具调用前可能已经输出音频，无法保证绝对静默。
- StepFun Prompt Realtime 当前没有声明工具能力，因此不能保存带工具的配置。Workflow Realtime 的既有行为不受这个 Prompt 门控影响。

切换运行模式或 Realtime Provider 不会自动删除工具配置。编辑器会显示不兼容项并提供显式清理操作；保存接口和会话启动都会再次校验，避免旧数据、inline config 或模型资源变更绕过能力限制。