ChatKit 架构与交互开发详解

大模型 API 可以生成文字、代码和结构化数据，但要让用户在回答里点击按钮、填写表单并查看结果，还需要一套界面与事件处理机制。OpenAI 的 ChatKit 提供了可嵌入的聊天界面、交互组件和服务端集成能力，帮助开发者把模型输出接入实际产品。

理解 ChatKit，关键是分清三件事。模型负责理解与生成，后端负责数据和操作，前端负责展示与交互。ChatKit 连接这些环节，但业务规则仍由应用实现。官方概览

本文面向准备开发 AI 聊天应用的开发者，介绍 ChatKit 的架构、Widget 和 Action，以及接入时需要承担的工作。文中的代码为局部示例，不能直接作为完整应用运行。功能与接入说明以 2026 年 10 月 8 日的官方文档为准。

1. ChatKit 在应用中的位置

用户在 ChatKit 界面发送消息，前端将请求交给应用后端。后端调用模型或 Agent，读取业务数据，再把文字和组件事件发送给前端。用户点击组件后，同一条链路继续处理操作。

从应用职责来看，可以分成五层：

自建集成可以连接自己的 Agent 服务。官方 Python SDK 提供与 Agents SDK 对接的辅助方法，开发者也可以在自己的后端编排模型调用。自建集成文档

例如订单助手中，模型可以判断用户需要查看物流，订单服务提供真实的物流状态，ChatKit 则展示结果和后续操作入口。是否允许查询某个订单，应由服务端根据用户身份判断。

2. 官方 SDK 与接入方式

React 项目可以安装官方 bindings：

npm install @openai/chatkit-react

官方前端接入文档还包含浏览器脚本加载步骤：

<script
  src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
  async
></script>

自建后端使用官方 Python 包：

pip install openai-chatkit

安装 SDK 之后，还需要配置后端端点、认证、存储和模型连接。所谓自建集成，主要指自己管理后端及业务编排；如果有完整离线部署要求，还需要核对前端资源的加载与分发方式。前端接入说明

当前官方支持自建后端，以及过渡期内已有的 Agent Builder 托管工作流。新项目应采用自建后端：Agent Builder 计划于 2026 年 11 月 30 日关闭，ChatKit 继续可用。当前接入路线

3. Widget 如何把回答变成组件

Widget 是 ChatKit 对话中的组件树。容器负责布局，子组件负责文字、状态和输入操作。常见组件包括卡片、列表、文本、按钮、表单与选择控件。官方 Widget Builder 可以预览布局，并生成对应 JSON。Widget 文档

下面的 Python 片段构建了一张带按钮的卡片。要让用户看到它，还需将组件通过 ChatKit 后端发送给前端。

from chatkit.widgets import Card, Text, Button, ActionConfig

widget = Card(
    children=[
        Text(value="找到一个符合预算的方案。"),
        Button(
            label="查看详情",
            onClickAction=ActionConfig(
                type="view_plan",
                payload={"plan_id": "plan_123"},
            ),
        ),
    ],
)

用户看到的是一张卡片和一个按钮。组件结构说明如何显示，按钮绑定的 Action 说明用户操作后应触发什么事件。

3.1 模型输出与组件构建

开发者可以让模型生成符合约束的组件数据，也可以让模型只返回业务结果，再由后端构建组件。例如模型输出推荐商品及理由，后端把这些字段填进固定商品卡片。

对于订单、商品和审批等业务场景，我更建议先使用固定模板。模型负责内容，后端控制展示字段和可执行操作，便于维护样式与业务规则。模型直接生成组件树则适合布局确实需要动态变化的场景，但仍要校验组件类型和字段。

ChatKit 接收的是它定义的组件协议。任意 JSON 需要转换，HTML 或 React 源代码也需要单独的运行环境。模型生成了一段页面代码，并不意味着 ChatKit 会执行它。

4. Action 如何处理用户操作

Action 表达一次用户操作。上面的按钮在点击后，会产生一个事件，类型为 view_plan，并携带方案 ID。下面是其核心字段示意，不代表完整的传输请求：

{
  "type": "view_plan",
  "payload": {
    "plan_id": "plan_123"
  }
}

Action 默认交给服务器处理。服务端实现 ChatKitServer.action()，可以查询业务数据、更新组件或继续调用模型。设置 handler="client" 后，则可由客户端回调处理，例如打开应用中的详情页面。表单内的输入值会随相应操作进入 payload。Action 文档

以“查看物流”为例，按钮点击后，前端发送订单 ID；后端验证访问权限，查询物流系统，再发送详情卡片。这个过程可以完全由业务代码完成。只有用户提出“解释一下为什么延误”等需求时，才可能需要模型参与。

4.1 Action 与工具调用的区别

两者可以复用同一个业务函数，但入口不同。用户点击按钮，也不代表客户端提供的参数天然可信。官方明确要求把 Action 及其 payload 当作不可信输入；身份、对象权限和允许的操作应在后端检查。事件处理说明

如果 Action 会创建订单或发送消息，应用还应考虑网络重试和重复点击。可以在业务接口中加入幂等处理，确保一次操作不会因重复请求执行多次。

5. 后端需要承担哪些工作

自建模式以 ChatKitServer 为核心。respond() 处理用户消息和客户端工具结果，action() 处理组件操作；HTTP 端点接收请求并调用 server.process()。

响应可以是 JSON，也可以是流式事件。stream_agent_response() 用于对接 Agent 输出，stream_widget() 用于发送组件及更新。通过 Store 保存会话和消息；支持上传时，还需要实现 FileStore。认证后的用户身份可以通过服务端 context 传递给存储与处理逻辑。后端接口说明

这些接口提供集成路径，实际模型选择、工具执行、业务数据库和访问控制仍由应用配置。开发时可以先采用内存存储；准备上线时，需要把会话与文件保存到持久化系统，并保证用户之间的数据隔离。

6. 外观定制与功能边界

ChatKit 支持主题、颜色、字体、界面密度和圆角配置，也可以调整欢迎文字、建议问题、输入框、附件、标题栏按钮、历史记录及语言。附件默认关闭，启用时还需配置上传方式。主题与定制文档

这些能力适合将聊天界面嵌入现有产品。完全自由的页面布局、3D 场景或任意 JavaScript 模拟，需要另外选择相应的前端实现。ChatGPT 中展示的交互可视化，也不能直接视为 ChatKit 的全部现成能力。

因此，选型时应先问：用户主要是在对话中完成选择和填写，还是需要一个自由布局的交互应用？前者适合评估 ChatKit，后者往往需要自定义界面，并把聊天作为其中一个入口。

7. ChatKit 与模型 API 的关系

一种实用的组合方式是：模型输出结构化业务结果，后端把结果转换成 Widget，ChatKit 展示组件，再通过 Action 接收用户操作。Structured Outputs 也提供界面生成的示例，但组件渲染和业务执行仍需要应用集成。结构化输出文档

这也解释了为什么支持交互回答不要求所有模型响应都改成 HTML。普通解释仍可以采用文字或 Markdown，需要用户操作的部分则由组件承担。

8. 从一个小闭环开始

第一次接入，可以选择一个具体业务场景，例如订单查询，先完成以下流程：

1. 用户发送问题，界面展示文字回答。
2. 后端查询数据，返回一张业务卡片。
3. 卡片按钮触发 Action，后端校验并处理。
4. 将处理结果展示为新消息或组件更新。
5. 保存会话，并验证重新打开后的行为。

在这个闭环运行稳定后，再加入表单、附件和动态组件生成。每增加一种界面能力，都应能对应到一个真实用户任务，以及明确的后端处理逻辑。

ChatKit 的价值在于提供聊天界面与交互协议，让开发者把精力投入模型编排和业务流程。是否采用它，取决于产品需要的界面自由度，以及团队愿意自行维护多少前端与会话基础设施。