ChatKit 是构建智能体聊天体验的最佳方式。无论您要开发的是内部知识库助手、员工入职助手、研究伙伴、购物或日程安排助手、故障排查机器人、财务规划顾问,还是客服智能体,都可以嵌入 ChatKit 提供的可定制聊天界面,由它处理用户体验的各项细节。
ChatKit 提供可嵌入的界面小组件、可定制的提示词、工具调用支持、文件附件和思维链可视化,让您无需从头开发聊天界面即可构建智能体。
概览
ChatKit 提供两种集成方式:
- 自定义服务器集成。在您自己的基础设施上运行 ChatKit。使用 ChatKit Python SDK 连接任意智能体服务,包括使用 Agents SDK 构建的服务。使用小组件构建前端。
- 现有的 Agent Builder 托管集成。如果您的 ChatKit 已连接到 Agent Builder 工作流,则可以在 Agent Builder 过渡期内继续使用该托管工作流。
OpenAI 正在逐步停用 Agent Builder。现有用户可以在过渡期内继续使用 Agent Builder,该产品计划于 2026 年 11 月 30 日停止服务。ChatKit 仍可使用。如果您要开发新应用或规划迁移,请使用 ChatKit 高级集成连接您自己的服务端智能体实现。有关 Agent Builder 过渡期的指导,请参阅从 Agent Builder 迁移。
开始使用 ChatKit
在前端嵌入 ChatKit
仅当您的 ChatKit 实现已使用 Agent Builder 工作流作为后端时,才采用这种方式。如果您要开发新的 ChatKit 应用,或要在 Agent Builder 停止服务前迁移,请使用高级集成将 ChatKit 连接到您自己的服务端智能体实现。
将 ChatKit 接入现有托管工作流大致分为三步。先在 Agent Builder 仍可使用时打开现有工作流,再设置 ChatKit,最后添加所需功能,打造您的聊天体验。

1. 使用现有托管工作流
在 Agent Builder 中打开现有工作流,即可获取工作流 ID。有关如何规划迁移,请参阅从 Agent Builder 迁移。
嵌入前端的聊天界面将连接到您选择的工作流。
2. 在产品中设置 ChatKit
要设置 ChatKit,您需要创建 ChatKit 会话和服务端端点,传入工作流 ID,换取客户端密钥,然后添加脚本,将 ChatKit 嵌入您的站点。
重要安全提示: 创建 ChatKit 会话时,您必须传入 user 参数,其值应能唯一标识每位最终用户。您的服务器必须验证应用用户的身份,并通过此参数传入该用户的唯一标识符。
-
在服务器上生成客户端令牌。
以下示例启动一个服务,通过 OpenAI API 创建 ChatKit 会话并返回该会话的客户端密钥:
Python# Replace the illustrative IDs and URLs below with your own resource values. import hmac import json import os from typing import Annotated import requests from fastapi import Depends, FastAPI, HTTPException from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer from pydantic import BaseModel api_key = os.environ["OPENAI_API_KEY"] workflow_id = "wf_123" authenticated_users: dict[str, str] = json.loads( os.environ["CHATKIT_AUTHENTICATED_USERS"] ) bearer_auth = HTTPBearer(auto_error=False) def get_authenticated_user_id( credentials: Annotated[ HTTPAuthorizationCredentials | None, Depends(bearer_auth), ], ) -> str: if credentials is not None: for token, user_id in authenticated_users.items(): if hmac.compare_digest(credentials.credentials, token): return user_id raise HTTPException(status_code=401, detail="Invalid authentication token") class ChatKitSession(BaseModel): client_secret: str app = FastAPI() @app.post("/api/chatkit/session") def create_chatkit_session( user_id: Annotated[str, Depends(get_authenticated_user_id)], ): response = requests.post( "https://api.openai.com/v1/chatkit/sessions", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", "OpenAI-Beta": "chatkit_beta=v1", }, json={ "workflow": {"id": workflow_id}, "user": user_id, }, timeout=30, ) response.raise_for_status() session = ChatKitSession.model_validate(response.json()) return {"client_secret": session.client_secret}如果使用 Ruby,请运行
gem install webrick安装 WEBrick。启动服务前,请将
wf_123替换为您的工作流 ID,并设置OPENAI_API_KEY和CHATKIT_AUTHENTICATED_USERS。后者的值是一个 JSON 映射,将应用的持有者令牌映射到稳定的用户 ID。在生产环境中,请使用应用自身的身份验证或会话查询机制来替代环境变量中的映射。 -
在服务端代码中,将工作流 ID 和密钥传给会话端点。
ChatKit 前端使用客户端密钥作为凭据来打开或刷新聊天会话。请勿存储客户端密钥,应立即将其交给 ChatKit 客户端库。
请参阅 GitHub 上的 chatkit-js 代码仓库。
如果使用 Go,请运行
go get github.com/openai/openai-go/v3@v3.70.0。如果使用 Java,请添加 Maven 依赖项com.openai:openai-java:4.75.1。创建 ChatKit 会话令牌TypeScriptexport default async function getChatKitSessionToken(deviceId: string) { const apiKey = process.env.OPENAI_API_KEY; if (!apiKey) { throw new Error("OPENAI_API_KEY is required"); } const response = await fetch("https://api.openai.com/v1/chatkit/sessions", { method: "POST", headers: { "Content-Type": "application/json", "OpenAI-Beta": "chatkit_beta=v1", Authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ workflow: { id: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1" }, user: deviceId, }), }); if (!response.ok) { throw new Error( `Failed to create a ChatKit session: ${response.status} ${await response.text()}` ); } const { client_secret } = await response.json(); if (!client_secret) { throw new Error("ChatKit session response did not include client_secret"); } return client_secret; } -
在项目目录中安装 ChatKit 的 React 绑定:
npm install @openai/chatkit-react -
将 ChatKit JS 脚本添加到页面。将以下代码片段放入页面的
<head>或其他加载脚本的位置,浏览器就会获取并运行 ChatKit。index.html<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js" async ></script> -
在界面中渲染 ChatKit。向 React 的
MyChat组件传入一个getAppAuthToken函数,让它返回当前用户的持有者令牌。如果使用 TypeScript 选项卡中的示例,请确保在代码片段的作用域内也能调用该函数。这段代码会将凭据发送到您的服务器,获取客户端密钥,然后挂载一个已连接到您的工作流的实时聊天小组件。前端代码reactimport { ChatKit, useChatKit } from '@openai/chatkit-react'; export function MyChat({ getAppAuthToken }) { const { control } = useChatKit({ api: { async getClientSecret(existing) { if (existing) { // implement session refresh } const appAuthToken = await getAppAuthToken(); const res = await fetch('/api/chatkit/session', { method: 'POST', headers: { 'Authorization': 'Bearer ' + appAuthToken, 'Content-Type': 'application/json', }, }); const { client_secret } = await res.json(); return client_secret; }, }, }); return <ChatKit control={control} className="h-[600px] w-[320px]" />; }
3. 开发与迭代
请参阅自定义主题、小组件和操作文档,进一步了解 ChatKit 的工作原理。您也可以利用以下资源测试聊天功能、改进提示词,以及添加小组件和工具。
开发您的 ChatKit 应用
了解如何处理身份验证、设置主题和定制界面等。
添加服务端存储、访问控制、工具和其他后端功能。
查看 ChatKit JS 代码仓库。
探索 ChatKit 界面
体验 ChatKit 交互式演示。
浏览可用的小组件。
通过交互式演示动手练习。
查看可运行的示例
查看可运行的 ChatKit 示例,获取开发灵感。
克隆代码仓库,以可直接运行的完整模板开始开发。
后续步骤
当 ChatKit 应用达到您的预期后,可以了解如何通过评估进一步优化它。如果您要开发新的 ChatKit 应用,或要将现有 ChatKit 应用从 Agent Builder 托管的工作流迁出,请参阅高级集成文档。

