ChatKit: Přehled a instalace
Na této stránce
Lekce přepsána 3. listopadu 2026. Předchozí verze popisovala API, které již neexistuje: objekt
new ChatKit({ apiKey, agentId }), komponentyChatProvider,ChatWindowaMessageInput, modul@openai/chatkit/reacta skriptcdn.openai.com/chatkit/…. Tato lekce nyní vychází z oficiálních průvodců OpenAI ChatKit, Python SDKopenai-chatkit1.6.5 a@openai/chatkit-react1.6.1. Příkladový server jsme spustili lokálně, abychom ověřili každý krok. Poznámka: Agent Builder bude ukončen 30. listopadu 2026; ChatKit zůstává k dispozici. Zdroje: ChatKit · Pokročilé integrace s ChatKit · Rychlý start Python SDK · Oficiální startovací aplikace.
Proč ChatKit
Vytvořil jsi agenta pomocí Agents SDK. Běží ve tvém terminálu a nikdo jiný ho nemůže používat. Aby ses dostal k uživatelům, potřebuješ konverzační rozhraní – a vybudovat kvalitní chatovací UI od nuly je drahé. Musíš řešit posouvání, streamování zpráv, obnovování konverzace, přílohy, zobrazování volání nástrojů a zpracování chybových stavů sítě.
ChatKit je odpovědí OpenAI: komponenta pro konverzaci, kterou vložíš do svého produktu a která se postará o celý uživatelský zážitek. Dokumentace zdůrazňuje interaktivní widgety, návrhy úvodních otázek, zobrazení volání nástrojů, přílohy a vizualizaci úvah agenta. Ty si ponecháš kontrolu nad tím podstatným: nad agentem, svými daty a svými pravidly.
Dva způsoby napájení
ChatKit je pouze rozhraní. Potřebuje server, který přijímá zprávy, spouští agenta a streamuje odpověď zpět. OpenAI popisuje dva přístupy:
| Cesta | Jak to funguje | Pro koho je určena |
|---|---|---|
| Váš vlastní ChatKit server (pokročilá integrace) | Váš Python server využívající SDK openai-chatkit přijímá požadavky z UI a spouští agenta dle vaší volby, například agenta z Agents SDK | Jakýkoli nový projekt: toto je cesta, kterou OpenAI doporučuje |
| Workflow hostované v Agent Builder | OpenAI spouští workflow navržené v Agent Builder; váš server pouze vytváří relace | Stávající integrace během přechodného období: Agent Builder bude ukončen 30. listopadu 2026 |
Tento kurz sleduje první cestu – jedinou, která má budoucnost. Druhou cestu shrneme na konci lekce pro ty, kteří musí udržovat stávající integraci až do jejího ukončení.
Architektura ze tří částí
Integrace ChatKit se skládá ze tří prvků. Rozlišení mezi nimi ti ušetří většinu začátečnických chyb:
- ChatKit.js, samotná komponenta: webová komponenta
<openai-chatkit>, která zobrazuje konverzaci v iframe. Načítá se z CDN OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), nikoli z npm: balíček npm@openai/chatkitobsahuje pouze její typové definice. - React vazby,
@openai/chatkit-react, které zpřístupňují komponentuChatKita hookuseChatKit. Jsou volitelné: bez Reactu ovládáš webovou komponentu přímo. - Váš ChatKit server, jediný HTTP endpoint, obvykle
/chatkit, který přijímá všechny požadavky z rozhraní. InstanceChatKitServerje směruje, spoléhá na úložiště (store) pro perzistenci vláken konverzace a spouští vašeho agenta.
Klíč API OpenAI nikdy neopustí server: rozhraní komunikuje pouze s vaším endpointem /chatkit.
Instalace
Na straně rozhraní nainstaluj React vazby a načti skript ChatKit na své stránce:
npm install @openai/chatkit-react
<!-- V části <head> vaší stránky -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Na straně serveru nainstaluj Python SDK ChatKit (Python 3.10 nebo novější), které přináší Agents SDK, plus webový server:
pip install openai-chatkit fastapi uvicorn
Minimální server
Níže uvedený server vychází z oficiálního rychlého startu. ChatKitServer vyžaduje pouze jednu metodu, respond, která se volá pro každou zprávu uživatele. Znovu načte nejnovější položky vlákna, převede je na vstup pro agenta pomocí simple_to_agent_input, spustí agenta ve streamovacím režimu a přeloží tento stream na události ChatKit 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 # in-memory store ze startovací aplikace
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žek vlákna, obnovených v chronologickém pořadí
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")
Spusť jej s OPENAI_API_KEY v prostředí: uvicorn main:app --port 8000.
Úložiště (store) si zaslouží dvě slova. ChatKit nic neukládá samo: vlákna, zprávy, widgety a volání nástrojů jsou perzistentní díky třídě, která dědí z chatkit.store.Store a implementuje asi tucet metod (load_thread, save_thread, load_thread_items, add_thread_item…). Pro začátek znovu použij soubor memory_store.py z oficiální startovací aplikace: udržuje vše v paměti, dokud proces běží. V produkci jej nahraď databází. Dokumentace doporučuje ukládat objekty jako JSON, aby aktualizace SDK nevynucovaly migrace schématu.
React rozhraní
Na straně rozhraní přijímá useChatKit konfiguraci a vrací objekt control, který předáš komponentě ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Ve vývojovém prostředí stačí zástupná hodnota; v produkci
// použijte svůj doménový klíč (viz níže)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Obsluhuj rozhraní a /chatkit ze stejného původu: ve vývoji se o to postará proxy tvého build nástroje (startovací aplikace konfiguruje proxy Vite pro přesměrování /chatkit na port 8000). Pokud server běží na jiném původu, explicitně jej povol, například pomocí CORSMiddleware ve FastAPI.
Bez Reactu
Web na WordPressu, aplikace v Rails nebo statická stránka mohou integrovat stejného asistenta: webová komponenta funguje přímo, jakmile se načte skript 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žnost, kterou uvidíš v následujících lekcích, má v obou případech stejnou formu: objekt předaný do useChatKit v Reactu nebo do setOptions na webové komponentě.
Bezpečnost od prvního dne
Tři pravidla, vycházející z produkčního průvodce ChatKit, platí již od fáze prototypu:
- Klíč API zůstává na serveru. Nesmí se objevit v kódu rozhraní ani ve vašem repozitáři: čti jej z proměnné prostředí nebo ze správce tajných klíčů.
- Ověřuj každý požadavek na
/chatkit. SDK toto nezpracovává: vaše aplikace musí ověřit relaci nebo token uživatele a poté předat jeho identitu doserver.processv kontextu (lekce 21). Bez toho může kdokoli spouštět vašeho agenta na vaše náklady. - Registruj své domény. Před spuštěním do produkce deklaruj každý hostname, který bude zobrazovat ChatKit, na stránce Domain allowlist platformy OpenAI a zkopíruj vygenerovaný klíč do
domainKey. Při načítání iframe ChatKit ověří tento klíč u OpenAI a odmítne se zobrazit, pokud chybí nebo neodpovídá.
Pokud již máte workflow v Agent Builder
Stávající integrace napojené na hostované workflow fungují až do ukončení Agent Builder. Jejich princip se liší: váš server vytvoří relaci ChatKit voláním POST https://api.openai.com/v1/chatkit/sessions s hlavičkou OpenAI-Beta: chatkit_beta=v1, ID workflow a identifikátorem user, který je jedinečný pro každého ověřeného uživatele. Následně vrátí získaný client_secret rozhraní. Na straně rozhraní pak možnost api přijímá funkci getClientSecret místo URL.
Nezačínej nový projekt na tomto modelu. Pro stávající integraci exportuj workflow do kódu Agents SDK a přejdi na vlastní ChatKit server před 30. listopadem 2026 podle průvodce Migrate from Agent Builder.
Klíčové poznatky
- ChatKit je rozhraní pro konverzaci připravené k integraci; váš server spouští agenta
- Pro jakýkoli nový projekt: váš vlastní ChatKit server (
pip install openai-chatkit) s metodouresponda endpointem/chatkit; hostovaný Agent Builder bude ukončen 30. listopadu 2026 - Rozhraní se načítá z CDN OpenAI; v Reactu použij
useChatKita<ChatKit control={control} />z@openai/chatkit-react - Úložiště (store) perzistuje vlákna konverzace: v paměti pro testování, v databázi pro produkci
- Klíč API pouze na serveru, ověřený
/chatkit, registrované domény pro získánídomainKey