客户端副作用

信息

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

客户端副作用用于将模型产生的“副作用事件”推送到前端执行，不打断模型推理流程，并使用服务端配置的默认值直接返回给模型。适用于：UI 更新、视图聚焦、高亮、动画、状态同步等只影响前端、不依赖返回值的场景。

核心特性

不中断对话：不等待前端返回结果
单向通知：模型 → 前端 UI
自动返回结果：使用中间件中配置的 Result
强 UI 表达能力：模型可“驱动界面变化”

工作流程

服务端配置 Client Effect 中间件
- 定义 Tool Name / Description / Arguments Schema
- 配置固定 Result
模型触发 Effect
- LLM 调用 Effect Tool（如 show_station）
前端接收并执行
- ChatKit 通过 onEffect 发送事件
- 前端执行 UI 副作用（更新状态、聚焦节点等）
模型继续推理
- 不等待前端执行完成

服务端配置要点

Tool Name

show_station

Arguments Schema（示例）

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

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Station name"
    }
  }
}

Result

It has already been shown to users

前端（React）接入

在 useChatKit 中注册 onEffect：

const handleClientEffect = useCallback(
  ({ name, data }) => {
    if (name === 'update_mindmap' && data?.mindmap) {
      setMindmap(convertMindmapFromSnake(data.mindmap));
    }

    if (name === 'focus_node' && data?.nodeId) {
      focusNode(data.nodeId);
    }
  },
  []
);

useChatKit({
  ...
  onEffect: handleClientEffect,
});

Client Tool vs Client Effect

对比项	Client Tool	Client Effect
是否中断推理	✅ 是	❌ 否
是否等待前端返回	✅ 是	❌ 否
是否返回动态结果	✅ 是	❌ 否（固定 Result）
适用场景	读取状态 / 用户确认	UI 更新 / 展示 / 聚焦

最佳实践

Effect 只做 UI 副作用，不承担业务决策
name 必须与服务端 Tool Name 完全一致
data 只包含前端执行所需的最小字段
不要在 Effect 中做耗时或阻塞操作

客户端副作用让模型可以“声明式地驱动 UI 行为”，是构建 可视化、强交互智能体体验 的关键能力。

核心特性​

工作流程​

服务端配置要点​

前端（React）接入​

Client Tool vs Client Effect​

最佳实践​