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