ChatKit: Przegląd i instalacja
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opisywała API, które już nie istnieje: obiekt
new ChatKit({ apiKey, agentId }), komponentyChatProvider,ChatWindowiMessageInput, moduł@openai/chatkit/reactoraz skryptcdn.openai.com/chatkit/…. Ta lekcja podąża teraz za oficjalnymi przewodnikami OpenAI ChatKit, Python SDKopenai-chatkitw wersji 1.6.5 oraz@openai/chatkit-reactw wersji 1.6.1. Uruchomiliśmy przykładowy serwer lokalnie, aby zweryfikować każdy krok. Uwaga: Agent Builder zostanie wyłączony 30 listopada 2026 r.; ChatKit pozostaje dostępny. Źródła: ChatKit · Zaawansowane integracje z ChatKit · Szybki start Python SDK · Oficjalna aplikacja startowa.
Dlaczego ChatKit
Stworzyłeś agenta za pomocą Agents SDK. Działa on w Twoim terminalu i nikt inny nie może z niego korzystać. Aby oddać go w ręce użytkowników, potrzebujesz interfejsu konwersacyjnego – a budowanie dobrego UI czatu od zera jest kosztowne. Musisz obsłużyć przewijanie, strumieniowanie wiadomości, wznawianie rozmów, załączniki, wyświetlanie wywołań narzędzi oraz obsługę błędów sieciowych.
ChatKit to odpowiedź OpenAI: komponent konwersacyjny, który osadzasz w swoim produkcie i który zajmuje się całym doświadczeniem użytkownika. Dokumentacja podkreśla jego interaktywne widżety, sugerowane pytania początkowe, wyświetlanie wywołań narzędzi, obsługę załączników oraz wizualizację rozumowania agenta. Ty zachowujesz kontrolę nad tym, co najważniejsze: agentem, swoimi danymi i swoimi regułami.
Dwa sposoby zasilania
ChatKit to tylko interfejs. Potrzebuje serwera, który otrzymuje wiadomości, uruchamia agenta i strumieniuje odpowiedź z powrotem. OpenAI opisuje dwa podejścia:
| Ścieżka | Jak to działa | Dla kogo |
|---|---|---|
| Twój własny serwer ChatKit (integracja zaawansowana) | Twój serwer Python, używający SDK openai-chatkit, otrzymuje żądania z UI i uruchamia wybranego przez Ciebie agenta, np. agenta z Agents SDK | Każdy nowy projekt: to ścieżka rekomendowana przez OpenAI |
| Przepływ pracy Hosted Agent Builder | OpenAI uruchamia przepływ pracy zaprojektowany w Agent Builder; Twój serwer jedynie tworzy sesje | Istniejące integracje w okresie przejściowym: Agent Builder zostanie wyłączony 30 listopada 2026 r. |
Ten kurs podąża pierwszą ścieżką – jedyną, która ma przyszłość. Podsumowujemy drugą na końcu lekcji dla tych, którzy muszą utrzymać istniejącą integrację do momentu wyłączenia.
Architektura złożona z trzech elementów
Integracja ChatKit sprowadza się do trzech elementów. Rozróżnienie ich pozwala uniknąć większości błędów początkujących:
- ChatKit.js, czyli sam komponent: element webowy
<openai-chatkit>, który wyświetla konwersację w iframe. Ładuje się z CDN OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), a nie z npm: pakiet npm@openai/chatkitzawiera jedynie jego definicje typów. - Powiązania z React,
@openai/chatkit-react, które udostępniają komponentChatKiti hookuseChatKit. Są opcjonalne: bez React kontrolujesz element webowy bezpośrednio. - Twój serwer ChatKit, pojedynczy punkt końcowy HTTP, konwencjonalnie
/chatkit, który otrzymuje wszystkie żądania z interfejsu. InstancjaChatKitServerroutuje je, polega na store (magazynie) do utrwalania wątków rozmów i uruchamia Twojego agenta.
Klucz API OpenAI nigdy nie opuszcza serwera: interfejs komunikuje się wyłącznie z Twoim punktem końcowym /chatkit.
Instalacja
Po stronie interfejsu zainstaluj powiązania z React i załaduj skrypt ChatKit na swojej stronie:
npm install @openai/chatkit-react
<!-- W sekcji <head> Twojej strony -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Po stronie serwera zainstaluj Python SDK ChatKit (Python 3.10 lub nowszy), które zawiera Agents SDK, oraz serwer WWW:
pip install openai-chatkit fastapi uvicorn
Minimalny serwer
Poniższy serwer podąża za oficjalnym szybkim startem. ChatKitServer wymaga tylko jednej metody, respond, wywoływanej dla każdej wiadomości użytkownika. Przeładowuje ona najnowsze elementy wątku, konwertuje je na dane wejściowe dla agenta za pomocą simple_to_agent_input, uruchamia agenta w trybie strumieniowym i tłumaczy ten strumień na zdarzenia ChatKit za pomocą 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 # magazyn w pamięci z aplikacji startowej
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]:
# Ostatnie 30 elementów wątku, przywrócone w kolejności chronologicznej
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")
Uruchom go, mając OPENAI_API_KEY w zmiennych środowiskowych: uvicorn main:app --port 8000.
Słowo o store (magazynie). ChatKit niczego nie przechowuje samodzielnie: wątki, wiadomości, widżety i wywołania narzędzi są utrwalane przez klasę dziedziczącą po chatkit.store.Store i implementującą około tuzina metod (load_thread, save_thread, load_thread_items, add_thread_item…). Na początek wykorzystaj ponownie plik memory_store.py z oficjalnej aplikacji startowej: przechowuje on wszystko w pamięci, dopóki proces działa. W środowisku produkcyjnym zastąp go bazą danych. Dokumentacja zaleca przechowywanie obiektów jako JSON, aby aktualizacje SDK nie wymuszały na Tobie migracji schematu.
Interfejs React
Po stronie interfejsu useChatKit otrzymuje konfigurację i zwraca obiekt control, który przekazujesz do komponentu ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// W środowisku deweloperskim wartość zastępcza wystarczy; w produkcji
// użyj swojego klucza domeny (patrz poniżej)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Obsługuj interfejs i /chatkit z tej samej origin: w środowisku deweloperskim zajmuje się tym proxy narzędzia buildowego (aplikacja startowa konfiguruje proxy Vite do przekierowania /chatkit na port 8000). Jeśli serwer znajduje się pod inną origin, zezwól na to jawnie, na przykład za pomocą CORSMiddleware w FastAPI.
Bez React
Strona WordPress, aplikacja Rails lub statyczna strona mogą zintegrować tego samego asystenta: element webowy działa bezpośrednio po załadowaniu skryptu 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>
Każda opcja, którą zobaczysz w kolejnych lekcjach, ma taką samą formę w obu przypadkach: obiekt przekazywany do useChatKit w React lub do setOptions w elemencie webowym.
Bezpieczeństwo od pierwszego dnia
Trzy zasady, zaczerpnięte z przewodnika produkcyjnego ChatKit, obowiązują już na etapie prototypu:
- Klucz API pozostaje na serwerze. Nie może pojawić się w kodzie interfejsu ani w Twoim repozytorium: odczytuj go ze zmiennej środowiskowej lub menedżera sekretów.
- Uwierzytelniaj każde żądanie do
/chatkit. SDK tego nie obsługuje: Twoja aplikacja musi zweryfikować sesję lub token użytkownika, a następnie przekazać jego tożsamość doserver.processw kontekście (lekcja 21). Bez tego każdy może uruchomić Twojego agenta na Twój koszt. - Zarejestruj swoje domeny. Przed uruchomieniem produkcyjnym zadeklaruj każdą nazwę hosta, która będzie wyświetlać ChatKit, na stronie Domain allowlist platformy OpenAI i skopiuj wygenerowany klucz do
domainKey. Podczas ładowania iframe ChatKit weryfikuje ten klucz z OpenAI i odmawia wyświetlenia, jeśli go brakuje lub nie pasuje.
Jeśli masz już przepływ pracy Agent Builder
Istniejące integracje podpięte pod hostowany przepływ pracy działają do momentu wyłączenia Agent Builder. Ich zasada jest inna: Twój serwer tworzy sesję ChatKit, wywołując POST https://api.openai.com/v1/chatkit/sessions, z nagłówkiem OpenAI-Beta: chatkit_beta=v1, ID przepływu pracy oraz identyfikatorem user unikalnym dla każdego uwierzytelnionego użytkownika. Następnie zwraca uzyskany client_secret do interfejsu. Po stronie interfejsu opcja api przyjmuje wtedy funkcję getClientSecret zamiast adresu URL.
Nie rozpoczynaj nowego projektu w oparciu o ten model. Dla istniejącej integracji wyeksportuj przepływ pracy do kodu Agents SDK i przełącz się na własny serwer ChatKit przed 30 listopada 2026 r., postępując zgodnie z przewodnikiem Migrate from Agent Builder.
Kluczowe wnioski
- ChatKit to gotowy do integracji interfejs konwersacyjny; Twój serwer uruchamia agenta
- Dla każdego nowego projektu: własny serwer ChatKit (
pip install openai-chatkit) z metodąrespondi punktem końcowym/chatkit; hostowany Agent Builder zostanie wyłączony 30 listopada 2026 r. - Interfejs ładuje się z CDN OpenAI; w React użyj
useChatKiti<ChatKit control={control} />z@openai/chatkit-react - Store (magazyn) utrwalają wątki rozmów: w pamięci do testów, w bazie danych w produkcji
- Klucz API tylko po stronie serwera, uwierzytelniony
/chatkit, zarejestrowane domeny w celu uzyskaniadomainKey