OpenAI AgentKit ChatKit Demo 实战

本文基于 OpenAI 最新发布的 AgentKit 及 ChatKit 组件,复现官方推荐的「后端创建 Session + 前端嵌入小部件」集成流程。你可以直接复制下方代码,在本地或生产环境中部署属于自己的 ChatKit 智能体体验。

架构与工作流

• AgentKit 工作流: 在 OpenAI 平台的 Agent Builder 中完成设计与发布,得到可复用的 workflow_id。Demo 同时演示简单对话与复杂推理两套工作流切换。
• FastAPI 服务端: 负责持有 OPENAI_API_KEY,通过 POST /v1/chatkit/sessions 为前端生成 client_secret,并代理 ChatKit CDN 以规避国内网络限制。
• React + @openai/chatkit-react 前端: 使用 ChatKit 组件嵌入聊天体验,结合自定义调试面板、主题与宽度调节,便于团队调试与演示。
• 安全与运维: Session 创建过程中不会泄露 API Key,Session 过期后前端自动刷新；日志中对敏感字段做遮罩,支持通过环境变量注入代理与自定义工作流。

Demo运行截图：

端到端流程

1. 用户在前端点击开始对话时,@openai/chatkit-react 会调用 getClientSecret。
2. 前端向 FastAPI 的 /api/chatkit/session?workflow_type=xxx 发起请求。
3. 服务端调用 OpenAI ChatKit 会话 API,返回 client_secret 与 session_id。
4. ChatKit 组件利用 client_secret 建立与 OpenAI 的安全长连接,加载对应工作流。
5. 如会话超时或网络中断,SDK 自动重试,并在调试面板中输出日志。

目录结构

chatkit-demo/
├── backend/            # FastAPI 后端
│   ├── main.py
│   └── requirements.txt
└── frontend/           # React + Vite 前端
    ├── package.json
    ├── vite.config.js
    └── src/
        ├── App.jsx
        ├── App.css
        ├── main.jsx
        └── index.css

环境准备

• Python 3.11+, Node.js ≥ 18。
• 设置环境变量:
  • OPENAI_API_KEY: 具备 AgentKit/ChatKit 权限的密钥。
  • WORKFLOW_ID(可选): 默认工作流,可在前端下拉切换。
  • HTTP_PROXY_FOR_REQUESTS(可选): 服务端调用 OpenAI API 时使用的代理。
  • DOMAIN_KEY(可选): 若需要在 iframe 中校验域名,可写入前端部署时的域名密钥。
• 前端打包后静态文件由 FastAPI 通过 StaticFiles 提供,也可交给 Nginx / CDN。

---

后端: FastAPI + OpenAI SDK代码

关键特性

• 在启动阶段移除系统代理环境变量,避免与 OpenAI 官方 SDK 冲突。
• 通过 /api/workflows 暴露前端可选工作流列表,避免硬编码。
• POST /api/chatkit/session 直接调度 REST API,同时兼容工作流版本与代理设定。
• /cdn/chatkit.js 提供 CDN 代理,附带浏览器 Header 绕过 Cloudflare 校验。
• 使用 uvicorn 热重载,便于本地开发。

🔒

付费内容

此内容仅限 Heliki AI 社区会员访问

还不是会员?

加入 Heliki AI 社区

加入后可在星球内获取最新访问密码

---

前端: React + ChatKit 组件代码

样式与交互亮点

• 使用 useChatKit 暴露的 control 对象接管会话生命周期,支持自动刷新 client_secret。
• 内置调试日志面板,友好展示 Session ID、工作流信息及错误追踪,同时对敏感字段做脱敏处理。
• 提供工作流切换、主题色调整、UI 密度与布局宽度调节,方便演示不同投放需求。
• 移动端自动切换为纵向布局,确保演示兼容性。

🔒

付费内容

此内容仅限 Heliki AI 社区会员访问

还不是会员?

加入 Heliki AI 社区

加入后可在星球内获取最新访问密码

---

部署与调试建议

• 本地开发: 启动顺序为 uvicorn main:app --reload 与 npm run dev。Vite 通过代理转发 /api 调用,避免手动配置跨域。
• 生产部署: 将前端打包 (npm run build) 后由 FastAPI StaticFiles 或 Nginx 托管,同时用 systemd 或 supervisor 常驻后端进程。
• 日志观察: 前端调试面板&后端 logging 会同时记录 Session ID,便于排查失败场景;如需更严格脱敏可增加自定义过滤器。
• 工作流管理: 在 OpenAI 平台发布新版本后更新 WORKFLOW_ID 或直接在前端切换,以验证不同推理配置对业务指标的影响。
• 安全加固: 生产环境务必限制 CORS 来源,并将 DOMAIN_KEY 注入部署域名,阻止未授权站点加载 ChatKit。

使用以上代码即可在 Heliki 社区文档中完整呈现 AgentKit ChatKit Demo,帮助读者快速上手官方推荐的集成方案。