OpenAI ChatKit 高级自托管集成

需要完全控制认证、数据驻留、本地部署或特定编排逻辑时，可以在自有基础设施运行ChatKit，使用自有服务器与定制界面。

Agent Builder托管的ChatKit工作流正处于过渡期。新ChatKit应用应使用ChatKit SDK和Agents SDK构建自己的服务端智能体实现，见ChatKit过渡指南。

在自有基础设施运行ChatKit

高级集成的总体流程是构建自己的ChatKit服务器，再用组件完善聊天界面。通过OpenAI API与ChatKit服务器，构建由OpenAI模型驱动的自定义聊天。

配置ChatKit服务器

按GitHub服务端指南处理请求、运行工具，并流式返回客户端。以下片段展示主要组成部分。

1. 安装服务端软件包

来源示例 1（bash）：

## [中文] 示例1：1. 安装服务端软件包。
## [中文] 安装ChatKit Python服务端包；安装本身不配置数据库、认证或部署服务器。
pip install openai-chatkit

2. 实现服务器类

ChatKitServer驱动对话。重写respond，在用户消息或客户端工具输出到达时流式产生事件；stream_agent_response等辅助方法用于连接Agents SDK。

来源示例 2（python）：

## [中文] 示例2：2. 实现服务器类。
## [中文] 加载当前线程最新20条项目，逆序后转换为智能体输入，构造AgentContext，再把Agents SDK流转换为ChatKit事件。
## [中文] 这是单页limit=20的来源片段，未遍历全部历史；assistant_agent、导入和存储实现由应用提供。
class MyChatKitServer(ChatKitServer[RequestContext]):
    async def respond(
        self,
        thread: ThreadMetadata,
        input: UserMessageItem | ClientToolCallOutputItem | None,
        context: RequestContext,
    ) -> AsyncIterator[Event]:
        items_page = await self.store.load_thread_items(
            thread.id,
            after=None,
            limit=20,
            order="desc",
            context=context,
        )
        input_items = await simple_to_agent_input(list(reversed(items_page.data)))
        agent_context = AgentContext(
            thread=thread,
            store=self.store,
            request_context=context,
        )
        result = Runner.run_streamed(
            assistant_agent,
            input_items,
            context=agent_context,
        )
        async for event in stream_agent_response(agent_context, result):
            yield event

3. 暴露端点

用所选框架把HTTP请求转发给服务器实例，例如FastAPI：

来源示例 3（python）：

## [中文] 示例3：3. 暴露端点。
## [中文] FastAPI端点将请求体交给ChatKitServer；流式结果使用text/event-stream，其他结果返回JSON。
## [中文] MemoryStore是本地演示存储；传入的上下文为空字典，真实用户认证、权限上下文和持久化需自行实现。
from fastapi import FastAPI, Request, Response
from fastapi.responses import StreamingResponse

app = FastAPI()
data_store = MemoryStore()
server = MyChatKitServer(data_store)


@app.post("/chatkit")
async def chatkit_endpoint(request: Request):
    result = await server.process(await request.body(), {})
    if isinstance(result, StreamingResult):
        return StreamingResponse(result, media_type="text/event-stream")
    return Response(content=result.json, media_type="application/json")

4. 建立数据存储约定

实现chatkit.store.Store，使用选定数据库保存线程、消息及文件。本地开发可用内存Store，生产应采用持久存储。可考虑把模型保存为JSON文档，使库更新演进schema时不必进行数据库迁移。

5. 提供文件存储约定

支持上传时实现FileStore。ChatKit既支持直接上传，即客户端POST文件到自有端点，也支持两阶段上传，即先获取签名URL、再上传到云存储。应开放预览以显示内联缩略图，并在线程删除时处理文件清理。

6. 从服务器触发客户端工具

客户端工具必须同时在客户端选项和智能体中注册。通过ctx.context.client_tool_call，从Agents SDK工具排入一次客户端调用。

来源示例 4（python）：

## [中文] 示例4：6. 从服务器触发客户端工具。
## [中文] 工具描述为“向用户的待办列表添加项目”，通过client_tool_call排入客户端调用；智能体指令是“你是乐于助人的助手”。
## [中文] 工具还须在客户端注册；StopAtTools让运行停在指定工具，代码没有在服务器直接完成待办持久写入。
@function_tool(description_override="Add an item to the user's todo list.")
async def add_to_todo_list(ctx: RunContextWrapper[AgentContext], item: str) -> None:
    ctx.context.client_tool_call = ClientToolCall(
        name="add_to_todo_list",
        arguments={"item": item},
    )


assistant_agent = Agent[AgentContext](
    model="gpt-6-astra",
    name="Assistant",
    instructions="You are a helpful assistant",
    tools=[add_to_todo_list],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[add_to_todo_list.name]),
)

7. 使用线程元数据与状态

thread.metadata用于保存服务端状态，例如上一轮Responses API运行ID或自定义标签。元数据不向客户端开放，但每次respond都可以访问。

8. 获取工具状态更新

长时间运行的工具可用ProgressUpdateEvent向界面流式显示进度。下一个助手消息或组件输出会替换该进度事件。

9. 使用服务器上下文

向server.process(body, context)传入自定义上下文，可在数据存储与文件存储实现中执行权限检查，或传递用户身份。

添加内联交互组件

组件可以在聊天中呈现卡片、表单、文本、列表等丰富界面。stream_widget可以立即渲染组件，也可以在更新到达时流式输出。

来源示例 5（python）：

## [中文] 示例5：添加内联交互组件。
## [中文] 构造含“生成的摘要”文字的Card，用stream_widget产生事件，并让存储生成项目ID。
## [中文] 保留来源respond片段的嵌入形式；self、thread、导入和组件类型应由服务器实现提供。
async def respond(
    self,
    thread: ThreadMetadata,
    input: UserMessageItem | ClientToolCallOutputItem | None,
    context: RequestContext,
) -> AsyncIterator[Event]:
    widget = Card(
        children=[
            Text(
                id="description",
                value="Generated summary",
            )
        ]
    )
    async for event in stream_widget(
        thread,
        widget,
        generate_id=lambda item_type: self.store.generate_item_id(
            item_type, thread, context
        ),
    ):
        yield event

ChatKit包含卡片、列表、表单、文字、按钮等多种节点，完整组件、属性和流式说明见GitHub组件指南。还可通过Widget Builder交互探索和创建组件。

使用动作

动作让界面在没有用户消息时触发工作。给支持的节点附加ActionConfig，按钮、选择框及其他控件即可流式生成线程项目或原地更新组件。组件位于Form中时，载荷会包含收集到的字段。

服务端实现ChatKitServer.action处理载荷，可选择继续流式返回事件；也可设置handler="client"，先在JavaScript客户端处理，再将后续工作交给服务器。

串联动作、强类型载荷及客户端/服务端协调见GitHub动作指南。

资源

通过以下资源和参考完成集成。

设计资源

• 下载OpenAI Sans Variable。
• 复制文件并按产品需要定制组件。

事件参考

ChatKit从Web Component发出CustomEvent实例。监听生命周期事件，并从event.detail读取载荷：

来源示例 6（javascript）：

// [中文] 示例6：事件参考。
// [中文] 监听错误、响应开始/结束、线程切换和日志事件，从event.detail读取载荷。
// [中文] 输出文字分别对应“响应开始”“响应结束”和“当前线程”；应用日志是否含敏感数据需按自己的记录策略处理。
chatkit.addEventListener("chatkit.error", (event) => {
  console.error(event.detail.error);
});

chatkit.addEventListener("chatkit.response.start", () => {
  console.log("Response started");
});

chatkit.addEventListener("chatkit.response.end", () => {
  console.log("Response ended");
});

chatkit.addEventListener("chatkit.thread.change", (event) => {
  console.log("Active thread:", event.detail.threadId);
});

chatkit.addEventListener("chatkit.log", (event) => {
  console.log(event.detail.name, event.detail.data);
});

选项参考

纯文本类型别名

• "light" | "dark"：明亮或深色。
• string | null：字符串或空值。
• object | boolean：对象或布尔值。