# 工具集成

工具（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) - 复杂对话流程