#介绍

chatkit 是给 Agent 应用用的对话界面：一个 npm 包 @volcengine/chatkit，提供会话列表、流式回答、思考与工具调用、输入框、附件等组件。依赖后端或业务实现的功能，需要接入对应能力后才能使用。

#接入方只面对三件事

const sessions = useChatSessions({ adapter, activeSessionId });

<Chatkit
  sessions={sessions}
  settings={{ locale: 'zh-CN', placeholder: '问点什么…' }}
  features={{ attachments: { upload }, edit: false }}
  slots={{ 'session.top': <Announcement /> }}
  renderers={{ parts: { 'acme.order': OrderCard }, tools: { get_weather: { detail: WeatherCard } } }}
  onSend={input => ({ ...input, metadata: { ...input.metadata, kb } })}
  onEvent={event => track(event)}
  onError={(error, context) => report(error, context)}
/>;

三条约定贯穿全部文档：

• 内置功能满足条件就显示，不满足就不显示。 向 SessionList 提供外部会话数组与操作回调后，可以显示业务会话目录；重新生成、编辑后重发也需要对应能力。能力函数存在并不代表请求一定成功，仍需处理接口错误。见内置功能总览。
• 没有插件机制。 业务功能（技能选择、知识库、收藏……）由业务方用插槽实现，见业务做法。
• 核心交互与指标口径不能定制。 发送、排队、停止、一轮的结论怎么判定，各个接入方一致，见不能定制的部分。

#包里有什么

#发送一条消息时会发生什么

后端 ──协议──▶ 适配器 ──事实──▶ 运行时 ──快照──▶ 会话层 ──▶ <Chatkit>
                 ▲                                           │
                 └────────── 命令（发送 / 停止 / 答复）◀──────┘

• 适配器只做翻译：把后端的流翻译成事实，把命令翻译成请求内容。请求由接入方的能力函数发出。
• 运行时管理对话状态：按后端的事件更新回答、工具调用和运行结果；连接断开不等于后端执行失败。
• 界面显示这些状态：输入草稿、面板开关等交互由界面管理。

#适合与不负责

• 适合：做一个对话式的 Agent 产品，后端是 ADK、A2A、OpenAI 兼容接口、Hermes，或者自有协议。
• 不负责：模型托管、密钥管理（前端只连自己的代理）、遥测上报服务（SDK 提供事件回调）。

#接下来

• 快速开始：不连后端先跑起来。
• 两种用法：完整应用，还是单个对话。
• 核心概念：适配器、配置、插槽分别是什么。