ChatKit: Prehľad a inštalácia
Na tejto strane
Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia popisovala API, ktoré už neexistuje: objekt
new ChatKit({ apiKey, agentId }), komponentyChatProvider,ChatWindowaMessageInput, modul@openai/chatkit/reacta skriptcdn.openai.com/chatkit/…. Táto lekcia teraz nasleduje oficiálne príručky OpenAI ChatKit, Python SDKopenai-chatkit1.6.5 a@openai/chatkit-react1.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:
| Cesta | Ako to funguje | Pre 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 SDK | Akýkoľvek nový projekt: toto je cesta, ktorú OpenAI odporúča |
| Workflow hostovaného Agent Builder | OpenAI spúšťa workflow navrhnuté v Agent Builder; tvoj server iba vytvára relácie | Existujú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:
- 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/chatkitobsahuje iba jeho typové definície. - React väzby,
@openai/chatkit-react, ktoré vystavujú komponentChatKita hákuseChatKit. Sú voliteľné: bez Reactu ovládaš webový komponent priamo. - Tvoj server ChatKit, jediný HTTP endpoint, konvenčne
/chatkit, ktorý prijíma všetky požiadavky z rozhrania. InštanciaChatKitServerich 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 doserver.processv 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ódouresponda endpointom/chatkit; hostovaný Agent Builder sa vypne 30. novembra 2026 - Rozhranie sa načítava z CDN OpenAI; v Reacte použite
useChatKita<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ískaniedomainKey