AI-VideoAssistant/docs/content/customization/tools.md

工具集成

工具（Tools）让助手能够执行外部操作，如查询天气、搜索信息、调用 API 等。

概述

工具是助手能力的扩展。当用户的请求需要外部数据或操作时，助手会调用相应的工具。

内置工具

工具	说明	参数
search	网络搜索	query: 搜索关键词
weather	天气查询	city: 城市名称
calculator	数学计算	expression: 计算表达式
knowledge	知识库检索	query: 查询内容

启用内置工具

在助手配置的 工具 标签页：

1. 勾选需要启用的工具
2. 配置工具参数（如有）
3. 保存配置

自定义工具

支持通过 HTTP 回调实现自定义工具。

定义工具

{
  "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. 助手继续生成回复

服务端事件

{
  "type": "assistant.tool_call",
  "data": {
    "tool_call_id": "call_abc123",
    "tool_name": "get_location",
    "arguments": {}
  }
}

客户端响应

{
  "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"
      }
    }
  ]
}

工具调用示例

天气查询

用户："北京今天天气怎么样？"

助手调用工具：

{
  "tool_name": "weather",
  "arguments": {
    "city": "北京"
  }
}

工具返回：

{
  "temperature": 25,
  "condition": "晴",
  "humidity": 40
}

助手回复："北京今天天气晴朗，气温 25 度，湿度 40%。"

订单查询

用户："帮我查一下订单 12345"

助手调用工具：

{
  "tool_name": "query_order",
  "arguments": {
    "order_id": "12345"
  }
}

工具返回：

{
  "order_id": "12345",
  "status": "已发货",
  "tracking": "SF1234567890"
}

助手回复："您的订单 12345 已发货，快递单号是 SF1234567890。"

工具配置最佳实践

1. 清晰的描述

工具描述应该让 LLM 准确理解何时使用：

好的描述：
"查询指定城市的实时天气信息，包括温度、天气状况和湿度"

不好的描述：
"天气工具"

2. 完整的参数定义

{
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称，如 '北京'、'上海'"
      },
      "date": {
        "type": "string",
        "description": "日期，格式 YYYY-MM-DD，可选，默认今天"
      }
    },
    "required": ["city"]
  }
}

3. 错误处理

工具应返回清晰的错误信息：

{
  "status": {
    "code": 404,
    "message": "未找到该城市的天气数据"
  }
}

安全注意事项

1. 验证输入 - 不要直接信任用户输入
2. 限制权限 - 工具只应有必要的权限
3. 审计日志 - 记录所有工具调用
4. 速率限制 - 防止滥用

下一步

• 知识库配置 - 让助手具备专业知识
• 工作流编排 - 复杂对话流程