230 lines
4.2 KiB
Markdown
230 lines
4.2 KiB
Markdown
# 工具集成
|
||
|
||
工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。
|
||
|
||
## 概述
|
||
|
||
工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。
|
||
|
||
## 内置工具
|
||
|
||
| 工具 | 说明 | 参数 |
|
||
|------|------|------|
|
||
| `search` | 网络搜索 | query: 搜索关键词 |
|
||
| `weather` | 天气查询 | city: 城市名称 |
|
||
| `calculator` | 数学计算 | expression: 计算表达式 |
|
||
| `knowledge` | 知识库检索 | query: 查询内容 |
|
||
|
||
### 启用内置工具
|
||
|
||
在助手配置的 **工具** 标签页：
|
||
|
||
1. 勾选需要启用的工具
|
||
2. 配置工具参数（如有）
|
||
3. 保存配置
|
||
|
||
## 自定义工具
|
||
|
||
支持通过 HTTP 回调实现自定义工具。
|
||
|
||
### 定义工具
|
||
|
||
```json
|
||
{
|
||
"name": "query_order",
|
||
"description": "查询用户订单信息",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"order_id": {
|
||
"type": "string",
|
||
"description": "订单编号"
|
||
}
|
||
},
|
||
"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. 助手继续生成回复
|
||
|
||
### 服务端事件
|
||
|
||
```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) - 复杂对话流程
|