Update documentation for Realtime Agent Studio with enhanced content and structure
- Revised site name and description for clarity and detail. - Updated navigation structure to better reflect the organization of content. - Improved changelog entries for better readability and consistency. - Migrated assistant configuration and prompt guidelines to new documentation paths. - Enhanced core concepts section to clarify the roles and capabilities of assistants and engines. - Streamlined workflow documentation to provide clearer guidance on configuration and usage.
This commit is contained in:
Xin Wang
@@ -1,38 +1,60 @@
|
||||
# 工具集成
|
||||
# 工具
|
||||
|
||||
工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。
|
||||
工具让助手从“会回答”扩展成“能执行动作”。本页是工具能力的正式说明页。
|
||||
|
||||
## 概述
|
||||
## 什么时候应该用工具
|
||||
|
||||
工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。
|
||||
当用户请求需要依赖外部系统、实时数据或执行某个动作时，应该使用工具，而不是只靠提示词或知识库。
|
||||
|
||||
## 内置工具
|
||||
典型场景包括：
|
||||
|
||||
| 工具 | 说明 | 参数 |
|
||||
|------|------|------|
|
||||
| `search` | 网络搜索 | query: 搜索关键词 |
|
||||
| `weather` | 天气查询 | city: 城市名称 |
|
||||
| `calculator` | 数学计算 | expression: 计算表达式 |
|
||||
| `knowledge` | 知识库检索 | query: 查询内容 |
|
||||
- 查询订单、库存、物流、天气等实时信息
|
||||
- 创建预约、提交表单、写入业务系统
|
||||
- 获取客户端环境能力，如定位、相机、权限确认
|
||||
|
||||
### 启用内置工具
|
||||
如果问题本质上是“查阅稳定资料”，优先用 [知识库](knowledge-base.md)；如果问题是“执行动作或读写实时状态”，优先用工具。
|
||||
|
||||
在助手配置的 **工具** 标签页：
|
||||
## 工具类型
|
||||
|
||||
1. 勾选需要启用的工具
|
||||
2. 配置工具参数（如有）
|
||||
3. 保存配置
|
||||
| 类型 | 说明 | 常见场景 |
|
||||
|------|------|----------|
|
||||
| **Webhook 工具** | 调用外部 HTTP API | 订单查询、CRM 写入、预约服务 |
|
||||
| **客户端工具** | 由接入端在本地执行 | 获取定位、打开相机、请求用户授权 |
|
||||
| **内建工具** | 平台或运行时直接提供 | 搜索、计算、知识检索等 |
|
||||
|
||||
## 自定义工具
|
||||
## 工具调用的基本过程
|
||||
|
||||
支持通过 HTTP 回调实现自定义工具。
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant Assistant as 助手 / 模型
|
||||
participant Tool as 工具
|
||||
|
||||
### 定义工具
|
||||
User->>Assistant: 发起请求
|
||||
Assistant->>Assistant: 判断是否需要工具
|
||||
Assistant->>Tool: 发起工具调用
|
||||
Tool-->>Assistant: 返回结构化结果
|
||||
Assistant->>User: 组织最终回复
|
||||
```
|
||||
|
||||
关键点不是“模型会不会调用工具”，而是“工具的定义是否足够清晰，能让模型在正确时机调用”。
|
||||
|
||||
## 如何定义一个好工具
|
||||
|
||||
| 要素 | 为什么重要 |
|
||||
|------|------------|
|
||||
| **清晰名称** | 让模型知道它是做什么的，而不是猜用途 |
|
||||
| **明确描述** | 告诉模型何时调用、何时不要调用 |
|
||||
| **完整参数定义** | 降低缺参、错参和歧义调用 |
|
||||
| **稳定返回结构** | 让模型更容易根据结果组织回复 |
|
||||
| **明确错误语义** | 让失败时也能安全退回用户对话 |
|
||||
|
||||
## Webhook 工具示例
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "query_order",
|
||||
"description": "查询用户订单信息",
|
||||
"description": "根据订单号查询当前订单状态，仅用于用户已提供订单号的场景。",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -42,188 +64,45 @@
|
||||
}
|
||||
},
|
||||
"required": ["order_id"]
|
||||
},
|
||||
"endpoint": {
|
||||
"url": "https://api.example.com/orders",
|
||||
"method": "GET",
|
||||
"headers": {
|
||||
"Authorization": "Bearer {{api_key}}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 工具字段说明
|
||||
## 客户端工具的作用
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| name | 工具名称（英文标识符） |
|
||||
| description | 工具描述（LLM 用于理解工具用途） |
|
||||
| parameters | 参数定义（JSON Schema 格式） |
|
||||
| endpoint | HTTP 调用配置 |
|
||||
某些动作必须在接入端执行，例如：
|
||||
|
||||
### 参数映射
|
||||
- 获取当前位置
|
||||
- 请求麦克风或相机权限
|
||||
- 打开特定页面或原生能力
|
||||
|
||||
工具参数自动映射到 HTTP 请求：
|
||||
这类工具通常通过事件流和客户端配合完成，而不是由后端直接执行。
|
||||
|
||||
- **GET 请求**：参数作为 query string
|
||||
- **POST 请求**：参数作为 JSON body
|
||||
## 工具设计建议
|
||||
|
||||
## 客户端工具
|
||||
- **一工具一职责**：不要把多个业务动作塞进同一个工具
|
||||
- **名称与描述写给模型看**：必须明确何时用、何时不用
|
||||
- **先设计错误返回**：失败时模型应该知道如何解释给用户
|
||||
- **减少高权限工具暴露面**：不是每个助手、每个工作流节点都需要全部工具
|
||||
- **把业务规则放回系统**：工具负责执行，提示词负责决策边界
|
||||
|
||||
某些工具需要在客户端执行（如获取地理位置）。
|
||||
## 与知识库、工作流的分工
|
||||
|
||||
### 工作流程
|
||||
- **知识库**：提供稳定事实
|
||||
- **工具**：执行动作或读取实时状态
|
||||
- **工作流**：决定何时进入某个步骤、调用哪个工具、失败如何回退
|
||||
|
||||
1. 助手返回 `assistant.tool_call` 事件
|
||||
2. 客户端执行工具并获取结果
|
||||
3. 客户端发送 `tool_call.results` 消息
|
||||
4. 助手继续生成回复
|
||||
当一个助手开始涉及多步骤、多系统调用时，工具通常应与 [工作流](workflows.md) 一起设计，而不是孤立配置。
|
||||
|
||||
### 服务端事件
|
||||
## 安全与治理
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "assistant.tool_call",
|
||||
"data": {
|
||||
"tool_call_id": "call_abc123",
|
||||
"tool_name": "get_location",
|
||||
"arguments": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
- 校验输入，不直接信任模型生成的参数
|
||||
- 为工具设置最小权限和清晰的可见范围
|
||||
- 记录调用日志，便于审计和回放
|
||||
- 对外部接口增加超时、重试和速率限制策略
|
||||
|
||||
### 客户端响应
|
||||
## 相关文档
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "tool_call.results",
|
||||
"results": [
|
||||
{
|
||||
"tool_call_id": "call_abc123",
|
||||
"name": "get_location",
|
||||
"output": {
|
||||
"latitude": 39.9042,
|
||||
"longitude": 116.4074,
|
||||
"city": "北京"
|
||||
},
|
||||
"status": {
|
||||
"code": 200,
|
||||
"message": "ok"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 工具调用示例
|
||||
|
||||
### 天气查询
|
||||
|
||||
用户："北京今天天气怎么样？"
|
||||
|
||||
助手调用工具：
|
||||
```json
|
||||
{
|
||||
"tool_name": "weather",
|
||||
"arguments": {
|
||||
"city": "北京"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
工具返回：
|
||||
```json
|
||||
{
|
||||
"temperature": 25,
|
||||
"condition": "晴",
|
||||
"humidity": 40
|
||||
}
|
||||
```
|
||||
|
||||
助手回复："北京今天天气晴朗，气温 25 度，湿度 40%。"
|
||||
|
||||
### 订单查询
|
||||
|
||||
用户："帮我查一下订单 12345"
|
||||
|
||||
助手调用工具：
|
||||
```json
|
||||
{
|
||||
"tool_name": "query_order",
|
||||
"arguments": {
|
||||
"order_id": "12345"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
工具返回：
|
||||
```json
|
||||
{
|
||||
"order_id": "12345",
|
||||
"status": "已发货",
|
||||
"tracking": "SF1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
助手回复："您的订单 12345 已发货，快递单号是 SF1234567890。"
|
||||
|
||||
## 工具配置最佳实践
|
||||
|
||||
### 1. 清晰的描述
|
||||
|
||||
工具描述应该让 LLM 准确理解何时使用：
|
||||
|
||||
```
|
||||
好的描述：
|
||||
"查询指定城市的实时天气信息，包括温度、天气状况和湿度"
|
||||
|
||||
不好的描述：
|
||||
"天气工具"
|
||||
```
|
||||
|
||||
### 2. 完整的参数定义
|
||||
|
||||
```json
|
||||
{
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string",
|
||||
"description": "城市名称，如 '北京'、'上海'"
|
||||
},
|
||||
"date": {
|
||||
"type": "string",
|
||||
"description": "日期，格式 YYYY-MM-DD，可选，默认今天"
|
||||
}
|
||||
},
|
||||
"required": ["city"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 错误处理
|
||||
|
||||
工具应返回清晰的错误信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": {
|
||||
"code": 404,
|
||||
"message": "未找到该城市的天气数据"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
1. **验证输入** - 不要直接信任用户输入
|
||||
2. **限制权限** - 工具只应有必要的权限
|
||||
3. **审计日志** - 记录所有工具调用
|
||||
4. **速率限制** - 防止滥用
|
||||
|
||||
## 下一步
|
||||
|
||||
- [知识库配置](knowledge-base.md) - 让助手具备专业知识
|
||||
- [工作流编排](workflows.md) - 复杂对话流程
|
||||
- [知识库](knowledge-base.md) - 当问题更适合“查资料”时使用知识库
|
||||
- [工作流](workflows.md) - 当工具调用需要流程控制和分支逻辑时接入工作流
|
||||
- [助手概念](../concepts/assistants.md) - 理解工具在助手能力层中的位置
|
||||
|
||||
Reference in New Issue
Block a user