Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

ChatKit: Prehľad a inštalácia

Lekcia 17 z 25 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Prečo ChatKit
  2. Dva spôsoby, ako ho poháňať
  3. Architektúra troch častí
  4. Inštalácia
  5. Minimálny server
  6. React rozhranie
  7. Bez Reactu
  8. Bezpečnosť od prvého dňa
  9. Ak už máš workflow Agent Builder
  10. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia popisovala API, ktoré už neexistuje: objekt new ChatKit({ apiKey, agentId }), komponenty ChatProvider, ChatWindow a MessageInput, modul @openai/chatkit/react a skript cdn.openai.com/chatkit/…. Táto lekcia teraz nasleduje oficiálne príručky OpenAI ChatKit, Python SDK openai-chatkit 1.6.5 a @openai/chatkit-react 1.6.1. Príkladový server sme spustili lokálne, aby sme overili každý krok. Poznámka: Agent Builder sa vypne 30. novembra 2026; ChatKit zostáva dostupný. Zdroje: ChatKit · Pokročilé integrácie s ChatKit · Rýchly štart Python SDK · Oficiálna štartovacia aplikácia.

Prečo ChatKit

Vytvoril si agenta pomocou Agents SDK. Beží vo tvojom termináli a nikto iný ho nemôže používať. Aby si ho dostal do rúk svojim používateľom, potrebuješ rozhranie pre konverzáciu – a vytvorenie dobrého chatovacieho UI od nuly je nákladné. Musíš riešiť rolovanie, streamovanie správ, obnovenie konverzácie, prílohy, zobrazovanie volaní nástrojov a spracovanie chyieb siete.

ChatKit je odpoveďou OpenAI: komponent pre konverzáciu, ktorý vložíš do svojho produktu a ktorý sa postará o celý používateľský zážitok. Dokumentácia zdôrazňuje jeho interaktívne widgety, počiatočné návrhy, zobrazovanie volaní nástrojov, prílohy a vizualizáciu uvažovania agenta. Ty si zachovávaš kontrolu nad tým, na čom záleží: nad agentom, svojimi dátami a svojimi pravidlami.

Dva spôsoby, ako ho poháňať

ChatKit je len rozhranie. Potrebuje server, ktorý prijíma správy, spúšťa agenta a streamuje odpoveď späť. OpenAI opisuje dva prístupy:

CestaAko to fungujePre koho je určená
Vlastný server ChatKit (pokročilá integrácia)Tvoj Python server, využívajúci SDK openai-chatkit, prijíma požiadavky z UI a spúšťa agenta podľa tvojej voľby, napríklad agenta z Agents SDKAkýkoľvek nový projekt: toto je cesta, ktorú OpenAI odporúča
Workflow hostovaného Agent BuilderOpenAI spúšťa workflow navrhnuté v Agent Builder; tvoj server iba vytvára relácieExistujúce integrácie počas prechodného obdobia: Agent Builder sa vypne 30. novembra 2026

Tento kurz nasleduje prvú cestu – jedinú, ktorá má budúcnosť. Druhú stručne zhrnieme na konci lekcie pre tých, ktorí potrebujú udržiavať existujúcu integráciu až do vypnutia.

Architektúra troch častí

Integrácia ChatKit sa redukuje na tri prvky. Ich rozlíšenie ti ušetrí väčšinu začiatočníckych chýb:

  1. ChatKit.js, samotný komponent: webový komponent <openai-chatkit>, ktorý zobrazuje konverzáciu v iframe. Načítava sa z CDN OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), nie z npm: balík npm @openai/chatkit obsahuje iba jeho typové definície.
  2. React väzby, @openai/chatkit-react, ktoré vystavujú komponent ChatKit a hák useChatKit. Sú voliteľné: bez Reactu ovládaš webový komponent priamo.
  3. Tvoj server ChatKit, jediný HTTP endpoint, konvenčne /chatkit, ktorý prijíma všetky požiadavky z rozhrania. Inštancia ChatKitServer ich smeruje, spolieha sa na úložisko (store) na trvalé uloženie vlákien konverzácie a spúšťa tvojho agenta.

API kľúč OpenAI nikdy neopustí server: rozhranie komunikuje iba s tvojim endpointom /chatkit.

Inštalácia

Na strane rozhrania nainštaluj React väzby a načítaj skript ChatKit do svojej stránky:

npm install @openai/chatkit-react
<!-- V časti <head> vašej stránky -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

Na strane servera nainštaluj Python SDK ChatKit (Python 3.10 alebo novší), ktoré so sebou prináša Agents SDK, plus webový server:

pip install openai-chatkit fastapi uvicorn

Minimálny server

Nižšie uvedený server nasleduje oficiálny rýchly štart. ChatKitServer vyžaduje iba jednu metódu, respond, ktorá sa volá pre každú správu používateľa. Znovu načíta najnovšie položky vlákna, prevedie ich na vstup pre agenta pomocou simple_to_agent_input, spustí agenta v režime streamovania a preloží tento stream na udalosti ChatKit pomocou 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  # úložisko v pamäti zo štartovacej aplikácie

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]:
        # Posledných 30 položiek vlákna, obnovených v chronologickom poradí
        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")

Spusti ho s premennou prostredia OPENAI_API_KEY: uvicorn main:app --port 8000.

Úložisko (store) si zaslúži dve slová. ChatKit nič neukladá samo: vlákna, správy, widgety a volania nástrojov ukladá trieda, ktorá dedí od chatkit.store.Store a implementuje asi tucet metód (load_thread, save_thread, load_thread_items, add_thread_item…). Na začiatok znovu použi súbor memory_store.py z oficiálnej štartovacej aplikácie: udržiava všetko v pamäti, kým proces beží. V produkcii ho nahraď databázou. Dokumentácia odporúča ukladať objekty ako JSON, aby aktualizácie SDK nevynucovali migrácie schémy.

React rozhranie

Na strane rozhrania useChatKit prijíma konfiguráciu a vracia objekt control, ktorý odovzdáš komponentu ChatKit:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function Assistant() {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      // Vo vývojovom prostredí stačí zástupná hodnota; v produkcii
      // použite svoj doménový kľúč (pozri nižšie)
      domainKey: 'local-dev',
    },
  });

  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}

Obsluhuj rozhranie a /chatkit z rovnakého pôvodu: vo vývoji to vybaví proxy tvojho nástroja na zostavenie (štartovacia aplikácia konfiguruje proxy Vite na presmerovanie /chatkit na port 8000). Ak server beží na inom pôvode, povoľ ho explicitne, napríklad pomocou CORSMiddleware vo FastAPI.

Bez Reactu

Stránka WordPress, aplikácia Rails alebo statická stránka môžu integrovať rovnakého asistenta: webový komponent funguje priamo po načítaní skriptu z 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ždá možnosť, ktorú uvidíš v nasledujúcich lekciách, má v oboch prípadoch rovnakú formu: objekt odovzdaný do useChatKit v Reacte alebo do setOptions na webovom komponente.

Bezpečnosť od prvého dňa

Tri pravidlá, prevzaté z produkčnej príručky ChatKit, platia už od fázy prototypu:

  • API kľúč zostáva na serveri. Nesmie sa objaviť v kóde rozhrania ani v tvojom repozitári: čítaj ho z premennej prostredia alebo správcu tajomstiev.
  • Overuj každú požiadavku na /chatkit. SDK toto nerieši: tvoja aplikácia musí overiť reláciu alebo token používateľa a potom odovzdať jeho identitu do server.process v kontexte (lekcia 21). Bez toho môže ktokoľvek spustiť tvojho agenta na tvoje náklady.
  • Registruj svoje domény. Pred spustením do prevádzky vyhlás každé hostname, ktoré bude zobrazovať ChatKit, na stránke Zoznam povolených domén platformy OpenAI a skopíruj vygenerovaný kľúč do domainKey. Pri načítaní iframe ChatKit overí tento kľúč u OpenAI a odmietne zobrazenie, ak chýba alebo sa nezhoduje.

Ak už máš workflow Agent Builder

Existujúce integrácie napojené na hostované workflow fungujú až do vypnutia Agent Builder. Ich princíp sa líši: tvoj server vytvorí reláciu ChatKit zavolaním POST https://api.openai.com/v1/chatkit/sessions, s hlavičkou OpenAI-Beta: chatkit_beta=v1, ID workflow a identifikátorom user, ktorý je jedinečný pre každého overeného používateľa. Následne vráti získaný client_secret rozhraniu. Na strane rozhrania potom možnosť api prijíma funkciu getClientSecret namiesto URL.

Nezačínaj nový projekt na tomto modeli. Pre existujúcu integráciu exportuj workflow do kódu Agents SDK a prepnite sa na vlastný server ChatKit pred 30. novembrom 2026 podľa príručky Migrácia z Agent Builder.

Kľúčové poznatky

  • ChatKit je rozhranie pre konverzáciu pripravené na integráciu; tvoj server spúšťa agenta
  • Pre akýkoľvek nový projekt: vlastný server ChatKit (pip install openai-chatkit) s metódou respond a endpointom /chatkit; hostovaný Agent Builder sa vypne 30. novembra 2026
  • Rozhranie sa načítava z CDN OpenAI; v Reacte použite useChatKit a <ChatKit control={control} /> z @openai/chatkit-react
  • Úložisko (store) trvalo ukladá vlákna konverzácie: v pamäti na testovanie, v databáze pre produkciu
  • API kľúč iba na strane servera, overený /chatkit, registrované domény na získanie domainKey