ChatKit: Преглед и инсталация
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия описваше API, което вече не съществува: обект
new ChatKit({ apiKey, agentId }), компонентиChatProvider,ChatWindowиMessageInput, модул@openai/chatkit/reactи скриптcdn.openai.com/chatkit/…. Този урок следва официалните ръководства на OpenAI за ChatKit, Python SDKopenai-chatkit1.6.5 и@openai/chatkit-react1.6.1. Стартирахме примерния сървър локално, за да проверим всяка стъпка. Забележка: Agent Builder спира работа на 30 ноември 2026 г.; ChatKit остава достъпен. Източници: ChatKit · Разширени интеграции с ChatKit · Бързо стартиране на Python SDK · Официално стартово приложение.
Защо ChatKit
Вие създадохте агент с Agents SDK. Той работи във вашия терминал и никой друг не може да го използва. За да го предоставите на потребителите си, Ви е необходим интерфейс за разговор – а изграждането на добър чат интерфейс от нулата е скъпо. Трябва да се справите със скролиране, поточно предаване на съобщения, възобновяване на разговора, прикачени файлове, визуализиране на извиквания на инструменти и обработка на мрежови грешки.
ChatKit е отговорът на OpenAI: компонент за разговор, който вграждате във вашия продукт и който поема целия потребителски опит. Документацията подчертава неговите интерактивни уиджети, начални предложения, визуализиране на извиквания на инструменти, прикачени файлове и визуализация на разсъжденията на агента. Вие запазвате контрол над важното: агента, вашите данни и вашите правила.
Два начина за захранването му
ChatKit е просто интерфейс. Той се нуждае от сървър, който получава съобщения, изпълнява агента и връща отговора чрез поточно предаване. OpenAI описва два подхода:
| Път | Как работи | За кого е предназначен |
|---|---|---|
| Вашият собствен ChatKit сървър (разширена интеграция) | Вашият Python сървър, използващ SDK openai-chatkit, получава заявки от интерфейса и изпълнява агента по ваш избор, например агент от Agents SDK | Всеки нов проект: това е пътят, препоръчан от OpenAI |
| Работен поток на Hosted Agent Builder | OpenAI изпълнява работен поток, проектиран в Agent Builder; вашият сървър само създава сесии | Съществуващи интеграции по време на преходния период: Agent Builder спира работа на 30 ноември 2026 г. |
Този курс следва първия път – единственият с бъдеще. Обобщаваме втория в края на урока за онези, които трябва да поддържат съществуваща интеграция до спирането ѝ.
Архитектура от три части
Интеграцията на ChatKit се свежда до три елемента. Разграничаването им избягва повечето грешки на начинаещите:
- ChatKit.js, самият компонент: уеб компонент
<openai-chatkit>, който показва разговора в iframe. Той се зарежда от CDN на OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), а не от npm: npm пакетът@openai/chatkitсъдържа само неговите дефиниции на типове. - React обвързвания,
@openai/chatkit-react, които излагат компонентаChatKitи кукаuseChatKit. Те са по избор: без React, Вие контролирате уеб компонента директно. - Вашият ChatKit сървър, единичен HTTP крайна точка, обикновено
/chatkit, която получава всички заявки от интерфейса. Екземпляр наChatKitServerги маршрутизира, разчита на хранилище (store) за запазване на нишките на разговора и изпълнява вашия агент.
API ключът на OpenAI никога не напуска сървъра: интерфейсът говори само с вашата крайна точка /chatkit.
Инсталация
От страна на интерфейса, инсталирайте React обвързванията и заредете ChatKit скрипта във вашата страница:
npm install @openai/chatkit-react
<!-- В <head> на вашата страница -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
От страна на сървъра, инсталирайте Python SDK за ChatKit (Python 3.10 или по-нова версия), който включва Agents SDK, плюс уеб сървър:
pip install openai-chatkit fastapi uvicorn
Минималният сървър
Сървърът по-долу следва официалното бързо стартиране. ChatKitServer изисква само един метод, respond, който се извиква за всяко потребителско съобщение. Той презарежда последните елементи на нишката, ги конвертира във вход за агента с simple_to_agent_input, изпълнява агента в режим на поточно предаване и превежда този поток в събития на ChatKit с stream_agent_response:
# main.py
from typing import Any, AsyncIterator
from agents import Agent, Runner
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse
from memory_store import MemoryStore # in-memory store from the starter app
assistant = Agent[AgentContext[dict[str, Any]]](
name="Product Assistant",
instructions="You help product users. Respond in English, briefly.",
model="gpt-6.1-sol",
)
class MyChatKitServer(ChatKitServer[dict[str, Any]]):
async def respond(
self,
thread: ThreadMetadata,
input_user_message: UserMessageItem | None,
context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
# The last 30 thread items, restored in chronological order
page = await self.store.load_thread_items(
thread.id, after=None, limit=30, order="desc", context=context
)
agent_input = await simple_to_agent_input(list(reversed(page.data)))
agent_context = AgentContext(thread=thread, store=self.store, request_context=context)
result = Runner.run_streamed(assistant, agent_input, context=agent_context)
async for event in stream_agent_response(agent_context, result):
yield event
app = FastAPI()
server = MyChatKitServer(MemoryStore())
@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
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")
Стартирайте го с OPENAI_API_KEY във вашата среда: uvicorn main:app --port 8000.
Хранилището (store) заслужава две думи. ChatKit не съхранява нищо самостоятелно: нишки, съобщения, уиджети и извиквания на инструменти се запазват от клас, който наследява chatkit.store.Store и имплементира около дузина метода (load_thread, save_thread, load_thread_items, add_thread_item…). За да започнете, използвайте повторно файла memory_store.py от официалното стартово приложение: той пази всичко в паметта, докато процесът работи. В производствена среда го заменете с база данни. Документацията препоръчва съхраняването на обекти като JSON, така че актуализациите на SDK да не Ви принуждават към миграции на схемата.
React интерфейсът
От страна на интерфейса, useChatKit получава конфигурацията и връща обект control, който предавате на компонента ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// В разработка е достатъчна стойност-заместител; в производство
// използвайте вашия ключ за домейн (вижте по-долу)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Сервирайте интерфейса и /chatkit от един и същи произход: в разработка, прокси инструментът за изграждане се справя с това (стартовото приложение конфигурира прокси на Vite да пренасочва /chatkit към порт 8000). Ако сървърът е на различен произход, разрешете го изрично, например с CORSMiddleware на FastAPI.
Без React
Сайт на WordPress, приложение на Rails или статична страница могат да интегрират същия асистент: уеб компонентът работи директно, след като скриптът от CDN се зареди.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
</head>
<body>
<div id="chat-root" style="height: 600px"></div>
<script>
const chatkit = document.createElement('openai-chatkit');
chatkit.setOptions({
api: { url: '/chatkit', domainKey: 'local-dev' },
});
document.getElementById('chat-root').append(chatkit);
</script>
</body>
</html>
Всяка опция, която ще видите в следващите уроци, има една и съща форма и в двата случая: обект, предаден на useChatKit в React, или на setOptions на уеб компонента.
Сигурност от първия ден
Три правила, взети от производственото ръководство на ChatKit, важат от етапа на прототипа:
- API ключът остава на сървъра. Той не трябва да се появява в кода на интерфейса или във вашето хранилище: прочетете го от променлива на средата или мениджър на тайни.
- Удостоверявайте всяка заявка към
/chatkit. SDK не се справя с това: вашето приложение трябва да провери сесията или токена на потребителя, след което да предаде неговата идентичност наserver.processв контекста (урок 21). Без това всеки може да изпълни вашия агент за ваша сметка. - Регистрирайте вашите домейни. Преди да пуснете в експлоатация, декларирайте всяко име на хост, което ще показва ChatKit, на страницата Domain allowlist на платформата на OpenAI и копирайте генерирания ключ в
domainKey. При зареждане iframe на ChatKit проверява този ключ с OpenAI и отказва да се покаже, ако липсва или не съвпада.
Ако вече имате работен поток на Agent Builder
Съществуващите интеграции, свързани с хостван работен поток, работят до спирането на Agent Builder. Тяхният принцип е различен: вашият сървър създава сесия на ChatKit, като извиква POST https://api.openai.com/v1/chatkit/sessions, със заглавката OpenAI-Beta: chatkit_beta=v1, ID на работния поток и идентификатор user, уникален за всеки удостоверяван потребител. След това той връща получения client_secret на интерфейса. От страна на интерфейса, опцията api тогава приема функция getClientSecret вместо URL.
Не започвайте нов проект по този модел. За съществуваща интеграция, експортирайте работния поток в код на Agents SDK и преминете към вашия собствен ChatKit сървър преди 30 ноември 2026 г., следвайки ръководството Migrate from Agent Builder.
Ключови изводи
- ChatKit е готов за интегриране интерфейс за разговор; вашият сървър изпълнява агента
- За всеки нов проект: вашият собствен ChatKit сървър (
pip install openai-chatkit), с методrespondи крайна точка/chatkit; хостваният Agent Builder спира работа на 30 ноември 2026 г. - Интерфейсът се зарежда от CDN на OpenAI; в React използвайте
useChatKitи<ChatKit control={control} />от@openai/chatkit-react - Хранилището (store) запазва нишките на разговора: в паметта за тестване, в база данни за производство
- API ключ само от страна на сървъра, удостоверен
/chatkit, регистрирани домейни за получаване наdomainKey