跳到主要内容

客户端工具

信息

了解如何定义工具让智能体操作客户端功能。

客户端工具用于将模型发起的工具调用路由到前端 UI 执行，并将执行结果返回给模型继续推理，适用于读取前端状态、用户交互、浏览器能力等场景。

Client tool middleware
客户端工具中间件

工作流程​

  1. 服务端配置 Client Tool

    • 在工作流中使用 Client Tool 中间件
    • 定义 Tool Name / Description / Arguments Schema

  2. 模型触发工具调用

    • LLM 根据上下文调用指定 Client Tool

  3. 前端接收并执行

    • ChatKit 通过 onClientTool 将调用消息发送到前端
    • 前端执行真实逻辑（UI / 本地状态）

  4. 返回结果

    • 前端返回 tool result
    • ChatKit 将结果回传给模型，继续生成回复

服务端配置要点​

Tool Name

  • 唯一标识，如：get_current_station
  • 必须与前端代码中的 name 完全一致

Arguments Schema

参数模式配置需符合 JSON Schema 规范：

{
  "type": "object",
  "properties": {}
}

前端（React）接入​

在 useChatKit 中注册 onClientTool：

const handleClientTool = async ({ name, tool_call_id, id }) => {
  if (name === 'get_current_station') {
    return {
      tool_call_id: tool_call_id || id,
      name,
      status: 'success',
      content: JSON.stringify({ /* tool result */ }),
    };
  }
};
useChatKit({
  ...
  onClientTool: handleClientTool,
});

返回结果格式​

  • tool_call_id：必须回填
  • status：success 或 error
  • content：字符串（推荐 JSON）
{
  "nodes": [...],
}

最佳实践​

  • Tool Name 强一致（服务端 = 前端）
  • 使用 useRef 读取最新 UI 状态，避免闭包问题
  • content 尽量精简，避免返回大对象
  • 失败场景使用 status: "error" 明确返回

客户端工具让 ChatKit 能安全、可控地与前端状态和用户交互集成，是实现 HITL（Human-in-the-loop） 与 UI 感知智能体 的关键能力。