Przejdź do głównej treści
Polski— Wybierz język
Menu

ChatKit: Przegląd i instalacja

Lekcja 17 z 25 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dlaczego ChatKit
  2. Dwa sposoby zasilania
  3. Architektura złożona z trzech elementów
  4. Instalacja
  5. Minimalny serwer
  6. Interfejs React
  7. Bez React
  8. Bezpieczeństwo od pierwszego dnia
  9. Jeśli masz już przepływ pracy Agent Builder
  10. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opisywała API, które już nie istnieje: obiekt new ChatKit({ apiKey, agentId }), komponenty ChatProvider, ChatWindow i MessageInput, moduł @openai/chatkit/react oraz skrypt cdn.openai.com/chatkit/…. Ta lekcja podąża teraz za oficjalnymi przewodnikami OpenAI ChatKit, Python SDK openai-chatkit w wersji 1.6.5 oraz @openai/chatkit-react w 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żkaJak to działaDla 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 SDKKażdy nowy projekt: to ścieżka rekomendowana przez OpenAI
Przepływ pracy Hosted Agent BuilderOpenAI uruchamia przepływ pracy zaprojektowany w Agent Builder; Twój serwer jedynie tworzy sesjeIstnieją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:

  1. 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/chatkit zawiera jedynie jego definicje typów.
  2. Powiązania z React, @openai/chatkit-react, które udostępniają komponent ChatKit i hook useChatKit. Są opcjonalne: bez React kontrolujesz element webowy bezpośrednio.
  3. Twój serwer ChatKit, pojedynczy punkt końcowy HTTP, konwencjonalnie /chatkit, który otrzymuje wszystkie żądania z interfejsu. Instancja ChatKitServer routuje 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ść do server.process w 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ą respond i punktem końcowym /chatkit; hostowany Agent Builder zostanie wyłączony 30 listopada 2026 r.
  • Interfejs ładuje się z CDN OpenAI; w React użyj useChatKit i <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 uzyskania domainKey