OpenAI ChatKit 入门与托管集成
ChatKit提供可定制的嵌入式聊天体验,可用于内部知识库、人力资源入职、研究、购物与日程安排、故障排查、财务规划或客户支持等助手。
通过可嵌入界面组件、可定制提示词、工具调用支持、附件及思维链可视化等能力,可以构建智能体体验,无需重新实现聊天界面。
概览
选择两条ChatKit路径之一:
- 自定义服务器集成:在自有基础设施运行ChatKit,使用ChatKit Python SDK连接智能体服务,包括以Agents SDK构建的服务;用组件构建前端。
- 现有Agent Builder托管集成:已经通过Agent Builder工作流使用ChatKit的用户,可以在Agent Builder过渡期继续使用该托管工作流。
Agent Builder正在弃用,计划于2026年11月30日关闭,ChatKit仍可用。新增应用或迁移规划应采用ChatKit高级集成,连接自己的服务端智能体实现;过渡指南见从Agent Builder迁移。
开始使用ChatKit
- 自定义服务器集成:结合服务器与ChatKit SDK,自定义聊天体验。
- 现有托管工作流:在过渡期连接已有Agent Builder工作流。
在前端嵌入ChatKit
只有已存在支撑ChatKit的Agent Builder工作流时,才使用这条路径。新应用或在关闭前迁移的应用,应通过高级集成连接自有服务端智能体实现。
与现有托管工作流集成大体分三步:在Agent Builder仍可用时打开已有工作流,然后配置ChatKit并添加功能。

1. 使用已有托管工作流
在Agent Builder打开已有工作流,取得工作流ID。过渡规划见迁移指南。嵌入前端的聊天会指向所选工作流。
2. 在产品中配置ChatKit
需要创建ChatKit会话与服务端端点、传入工作流ID、交换客户端秘密,再添加嵌入脚本。
安全要求:创建会话必须提供user参数,每位最终用户应有独立标识。服务器必须先认证应用用户,再把其唯一标识传给该参数。
- 在服务器生成客户端令牌。下例启动服务,通过OpenAI API创建ChatKit会话并返回会话的客户端秘密:
来源示例 1(python):
## [中文] 示例1:2. 在产品中配置ChatKit。
## [中文] 服务端先验证应用Bearer令牌,从环境中的演示映射取得稳定用户ID,再用服务器API密钥创建ChatKit会话。
## [中文] wf_123须替换为已有工作流;只返回client_secret。生产应改用真实应用认证,不能信任前端自行声称的user。
## 把下方示例 ID 和 URL 换成你自己的资源值。
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}
来源示例 2(ruby):
## [中文] 示例2:2. 在产品中配置ChatKit。
## [中文] 启动仅监听本机的WEBrick服务;只处理指定POST端点,校验Bearer令牌后创建会话,返回客户端秘密。
## [中文] 环境映射用于演示,错误令牌返回401、上游异常返回502;真实部署的令牌比较、超时及刷新须另行验证。
## 把下方示例 ID 和 URL 换成你自己的资源值。
require "json"
require "net/http"
require "openssl"
require "webrick"
api_key = ENV.fetch("OPENAI_API_KEY")
workflow_id = "wf_123"
## Demo authentication mapping. Replace this with your application's session authentication.
authenticated_users = JSON.parse(ENV.fetch("CHATKIT_AUTHENTICATED_USERS"))
server = WEBrick::HTTPServer.new(
BindAddress: "127.0.0.1", Port: Integer(ENV.fetch("PORT", "8000")),
AccessLog: [], Logger: WEBrick::Log.new($stderr, WEBrick::BasicLog::WARN)
)
server.mount_proc("/api/chatkit/session") do |request, response|
response["Content-Type"] = "application/json"
response["Cache-Control"] = "no-store"
unless request.path == "/api/chatkit/session" && request.request_method == "POST"
response.status = 405
response.body = JSON.generate(error: "Use POST /api/chatkit/session")
next
end
token = request["Authorization"].to_s.delete_prefix("Bearer ")
user = authenticated_users.find do |credential, _id|
request["Authorization"].to_s.start_with?("Bearer ") &&
OpenSSL.secure_compare(credential, token)
end
unless user
response.status = 401
response.body = JSON.generate(error: "Invalid authentication token")
next
end
uri = URI("https://api.openai.com/v1/chatkit/sessions")
upstream = Net::HTTP::Post.new(uri)
upstream["Authorization"] = "Bearer #{api_key}"
upstream["Content-Type"] = "application/json"
upstream["OpenAI-Beta"] = "chatkit_beta=v1"
upstream.body = JSON.generate(workflow: { id: workflow_id }, user: user.fetch(1))
begin
result = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
http.request(upstream)
end
result.value
secret = JSON.parse(result.body).fetch("client_secret")
raise "Missing session secret" unless secret.is_a?(String) && !secret.empty?
response.body = JSON.generate(client_secret: secret)
rescue
response.status = 502
response.body = JSON.generate(error: "Unable to create a ChatKit session")
end
end
trap("INT") { server.shutdown }
trap("TERM") { server.shutdown }
puts("http://127.0.0.1:#{server.config[:Port]}/api/chatkit/session")
$stdout.flush
server.start
Ruby需先运行gem install webrick。启动服务前,将wf_123换成自己的工作流ID,设置OPENAI_API_KEY与CHATKIT_AUTHENTICATED_USERS;后者是应用Bearer令牌到稳定用户ID的JSON映射。生产中应换成应用自己的认证或会话查询。
- 在服务端向会话端点提供工作流ID与秘密密钥。客户端秘密是ChatKit前端打开或刷新聊天会话的凭证,不应将其存储起来,而应立即交给ChatKit客户端库。相关代码见chatkit-js仓库。
Go使用go get github.com/openai/openai-go/v3@v3.70.0;Java添加Maven依赖com.openai:openai-java:4.75.1。以下创建会话令牌:
来源示例 3(javascript):
// [中文] 示例3:2. 在产品中配置ChatKit。
// [中文] 在服务器创建ChatKit会话,检查HTTP响应与client_secret;示意工作流ID须替换。
// [中文] 参数名deviceId沿用来源,但传入值必须来自已认证的稳定用户身份;不能直接信任客户端提供的设备ID,API密钥不下发浏览器。
export default async function getChatKitSessionToken(deviceId) {
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;
}
来源示例 4(go):
// [中文] 示例4:2. 在产品中配置ChatKit。
// [中文] 在完成应用认证后调用此Go函数,以认证上下文中的稳定用户ID创建会话;不用客户端设备ID冒充用户。
// [中文] 返回client_secret或错误;需准备context、openai导入、客户端和实际工作流,原片段不是完整main程序。
// Call after authenticating the request. Pass the user's stable ID from your
// server-side authentication context, never a client-supplied device ID.
func getChatKitSessionToken(ctx context.Context, client openai.Client, authenticatedUserID string) (string, error) {
// Replace this illustrative workflow ID with your published workflow.
session, err := client.Beta.ChatKit.Sessions.New(ctx, openai.BetaChatKitSessionNewParams{
User: authenticatedUserID,
Workflow: openai.ChatSessionWorkflowParam{
ID: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1",
},
})
if err != nil {
return "", err
}
return session.ClientSecret, nil
}
来源示例 5(java):
// [中文] 示例5:2. 在产品中配置ChatKit。
// [中文] Java在服务端用已认证用户ID创建会话并返回clientSecret;替换示意工作流ID。
// [中文] 这是含静态方法的嵌入片段,需要适当的类、依赖及认证调用方,不应直接当作完整独立Java文件。
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.chatkit.sessions.*;
import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;
// Call after authenticating the request. Pass the user's stable ID from your
// server-side authentication context, never a client-supplied device ID.
static String getChatKitSessionToken(OpenAIClient client, String authenticatedUserId) {
// Replace this illustrative workflow ID with your published workflow.
return client
.beta()
.chatkit()
.sessions()
.create(
SessionCreateParams.builder()
.user(authenticatedUserId)
.workflow(
ChatSessionWorkflowParam.builder()
.id("wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1")
.build())
.build())
.clientSecret();
}
- 安装React绑定:在项目目录执行:
来源示例 6(bash):
## [中文] 示例6:2. 在产品中配置ChatKit。
## [中文] 在前端项目安装ChatKit React绑定;此命令只安装依赖,不创建后端会话。
npm install @openai/chatkit-react
- 加入ChatKit JS脚本:把以下片段放入页面
<head>或其他脚本加载位置,由浏览器获取并运行ChatKit:
来源示例 7(html):
<!-- [中文] 示例7:2. 在产品中配置ChatKit。 -->
<!-- [中文] 由浏览器从官方CDN异步加载ChatKit脚本;本段是页面HTML,不包含服务器API密钥。 -->
<script
src = "https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
async
></script>
- 在界面渲染ChatKit:向React的
MyChat组件传入getAppAuthToken,由它返回当前用户的Bearer令牌。使用JavaScript片段时,也要在其作用域提供同名函数。代码把该凭证发送到自有服务器,取得客户端秘密,再挂载连接工作流的聊天组件。
来源示例 8(javascript):
// [中文] 示例8:2. 在产品中配置ChatKit。
// [中文] 找到已加载的ChatKit元素,配置getClientSecret,用getAppAuthToken取得应用令牌,再请求自有服务器。
// [中文] 先检查HTTP是否成功,再返回client_secret;还需准备my-chat元素、脚本和getAppAuthToken。
const chatkit = document.getElementById("my-chat");
if (
!chatkit ||
!("setOptions" in chatkit) ||
typeof chatkit.setOptions !== "function"
) {
throw new Error("ChatKit element not found.");
}
chatkit.setOptions({
api: {
async getClientSecret() {
const appAuthToken = await getAppAuthToken();
const res = await fetch("/api/chatkit/session", {
method: "POST",
headers: {
Authorization: `Bearer ${appAuthToken}`,
"Content-Type": "application/json",
},
});
if (!res.ok) {
throw new Error(`ChatKit session request failed: ${res.status}`);
}
const { client_secret } = await res.json();
return client_secret;
},
},
});
来源示例 9(tsx):
// [中文] 示例9:2. 在产品中配置ChatKit。
// [中文] React使用useChatKit取得control,再渲染600px高、320px宽的ChatKit组件;返回元素按同页HTML恢复。
// [中文] getAppAuthToken应返回当前已认证用户的应用令牌。existing分支中的会话刷新尚待实现,来源片段也未检查res.ok,不能宣称刷新或错误处理已经完整。
import { 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. 构建与迭代
继续了解主题定制、组件与动作,或使用下面资源测试聊天、调整提示词、添加组件和工具。
构建实现
- GitHub上的ChatKit文档:认证、主题与定制。
- ChatKit Python SDK:服务端存储、访问控制、工具及其他后端能力。
- ChatKit JS SDK:JavaScript仓库。
探索ChatKit界面
- chatkit.world:交互演示。
- Widget Builder:浏览可用组件。
- ChatKit Playground:通过交互演示边做边学。
查看可运行示例
后续步骤
完成ChatKit实现后,通过评测优化。新应用,或希望把现有应用从Agent Builder托管工作流迁出的情况,继续阅读高级集成。