b300b469dc
- 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.
109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# 工具
|
|
|
|
工具让助手从“会回答”扩展成“能执行动作”。本页是工具能力的正式说明页。
|
|
|
|
## 什么时候应该用工具
|
|
|
|
当用户请求需要依赖外部系统、实时数据或执行某个动作时，应该使用工具，而不是只靠提示词或知识库。
|
|
|
|
典型场景包括：
|
|
|
|
- 查询订单、库存、物流、天气等实时信息
|
|
- 创建预约、提交表单、写入业务系统
|
|
- 获取客户端环境能力，如定位、相机、权限确认
|
|
|
|
如果问题本质上是“查阅稳定资料”，优先用 [知识库](knowledge-base.md)；如果问题是“执行动作或读写实时状态”，优先用工具。
|
|
|
|
## 工具类型
|
|
|
|
| 类型 | 说明 | 常见场景 |
|
|
|------|------|----------|
|
|
| **Webhook 工具** | 调用外部 HTTP API | 订单查询、CRM 写入、预约服务 |
|
|
| **客户端工具** | 由接入端在本地执行 | 获取定位、打开相机、请求用户授权 |
|
|
| **内建工具** | 平台或运行时直接提供 | 搜索、计算、知识检索等 |
|
|
|
|
## 工具调用的基本过程
|
|
|
|
```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": "根据订单号查询当前订单状态，仅用于用户已提供订单号的场景。",
|
|
"parameters": {
|
|
"type": "object",
|
|
"properties": {
|
|
"order_id": {
|
|
"type": "string",
|
|
"description": "订单编号"
|
|
}
|
|
},
|
|
"required": ["order_id"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## 客户端工具的作用
|
|
|
|
某些动作必须在接入端执行，例如：
|
|
|
|
- 获取当前位置
|
|
- 请求麦克风或相机权限
|
|
- 打开特定页面或原生能力
|
|
|
|
这类工具通常通过事件流和客户端配合完成，而不是由后端直接执行。
|
|
|
|
## 工具设计建议
|
|
|
|
- **一工具一职责**：不要把多个业务动作塞进同一个工具
|
|
- **名称与描述写给模型看**：必须明确何时用、何时不用
|
|
- **先设计错误返回**：失败时模型应该知道如何解释给用户
|
|
- **减少高权限工具暴露面**：不是每个助手、每个工作流节点都需要全部工具
|
|
- **把业务规则放回系统**：工具负责执行，提示词负责决策边界
|
|
|
|
## 与知识库、工作流的分工
|
|
|
|
- **知识库**：提供稳定事实
|
|
- **工具**：执行动作或读取实时状态
|
|
- **工作流**：决定何时进入某个步骤、调用哪个工具、失败如何回退
|
|
|
|
当一个助手开始涉及多步骤、多系统调用时，工具通常应与 [工作流](workflows.md) 一起设计，而不是孤立配置。
|
|
|
|
## 安全与治理
|
|
|
|
- 校验输入，不直接信任模型生成的参数
|
|
- 为工具设置最小权限和清晰的可见范围
|
|
- 记录调用日志，便于审计和回放
|
|
- 对外部接口增加超时、重试和速率限制策略
|
|
|
|
## 相关文档
|
|
|
|
- [知识库](knowledge-base.md) - 当问题更适合“查资料”时使用知识库
|
|
- [工作流](workflows.md) - 当工具调用需要流程控制和分支逻辑时接入工作流
|
|
- [助手概念](../concepts/assistants.md) - 理解工具在助手能力层中的位置
|