101 lines
5.0 KiB
Plaintext
101 lines
5.0 KiB
Plaintext
---
|
||
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 或模型资源变更绕过能力限制。
|