Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

ChatKit: Přehled a instalace

Lekce 17 z 25 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Proč ChatKit
  2. Dva způsoby napájení
  3. Architektura ze tří částí
  4. Instalace
  5. Minimální server
  6. React rozhraní
  7. Bez Reactu
  8. Bezpečnost od prvního dne
  9. Pokud již máte workflow v Agent Builder
  10. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze popisovala API, které již neexistuje: objekt new ChatKit({ apiKey, agentId }), komponenty ChatProvider, ChatWindow a MessageInput, modul @openai/chatkit/react a skript cdn.openai.com/chatkit/…. Tato lekce nyní vychází z oficiálních průvodců OpenAI ChatKit, Python SDK openai-chatkit 1.6.5 a @openai/chatkit-react 1.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:

CestaJak to fungujePro 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 SDKJakýkoli nový projekt: toto je cesta, kterou OpenAI doporučuje
Workflow hostované v Agent BuilderOpenAI spouští workflow navržené v Agent Builder; váš server pouze vytváří relaceStá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:

  1. 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/chatkit obsahuje pouze její typové definice.
  2. React vazby, @openai/chatkit-react, které zpřístupňují komponentu ChatKit a hook useChatKit. Jsou volitelné: bez Reactu ovládáš webovou komponentu přímo.
  3. Váš ChatKit server, jediný HTTP endpoint, obvykle /chatkit, který přijímá všechny požadavky z rozhraní. Instance ChatKitServer je 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 do server.process v 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 metodou respond a endpointem /chatkit; hostovaný Agent Builder bude ukončen 30. listopadu 2026
  • Rozhraní se načítá z CDN OpenAI; v Reactu použij useChatKit a <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