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

Pokročilá integrace do vaší aplikace

Lekce 21 z 25 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Co zbývá po demu
  2. Autentizuj každý požadavek
  3. Každý uživatel má své vlastní konverzace
  4. Poskytni modelu kontext své aplikace
  5. Klientské nástroje
  6. Řiď ChatKit ze své aplikace
  7. Sleduj, co se děje
  8. Než přejdeš do produkce
  9. Klíčové poznatky

Lekce přepsána 3. listopadu 2026. Předchozí verze spoléhala na vymyšlené vlastnosti a události (ChatProvider, režim „sidebar“, perzistence založená na UI). Nyní následuje návody Python SDK openai-chatkit 1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) a typy @openai/chatkit-react 1.6.1: kód serveru byl lokálně spuštěn a React kód ověřen kompilací. Zdroje: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.

Co zbývá po demu

Předchozí čtyři lekce ti poskytly funkčního asistenta. Aby mohl žít v reálném produktu, potřebuje to, co odděluje demo od služby: vědět, kdo mluví, zobrazovat každému uživateli pouze jeho konverzace, interagovat se zbytkem aplikace a být pozorovatelný. Tato lekce pokrývá tyto body jeden po druhém.

Autentizuj každý požadavek

SDK nepředpokládá nic o tvé autentizaci: umožňuje ti ověřit uživatele a poté předat jeho identitu do server.process v kontextu požadavku. Tento kontext doprovází každé volání: najdeš ho v respond, v action, v úložišti (store) a v nástrojích agenta.

Na straně rozhraní možnost api.fetch nahrazuje funkci fetch používanou ChatKitem. Zde přidáš relační token své aplikace:

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

export function ConnectedAssistant({ obtainToken }: { obtainToken: () => Promise<string> }) {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      domainKey: 'local-dev',
      fetch: async (input, init) => {
        // Zachovej hlavičky nastavené ChatKitem, pak přidej naše
        const headers = new Headers(init?.headers);
        headers.set('Authorization', `Bearer ${await obtainToken()}`);
        return fetch(input, { ...init, headers });
      },
    },
  });

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

Na straně serveru závislost FastAPI ověří token a sestaví kontext. Jazyk rozhraní přichází v hlavičce Accept-Language, kterou ChatKit posílá s každým požadavkem:

from dataclasses import dataclass

from chatkit.server import StreamingResult
from chatkit.store import NotFoundError
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import Response, StreamingResponse


@dataclass
class RequestContext:
    user_id: str
    locale: str


async def current_user(request: Request) -> str:
    token = request.headers.get("authorization", "").removeprefix("Bearer ")
    user_id = await verify_token(token)  # tvá autentizace: session, JWT...
    if not user_id:
        raise HTTPException(status_code=401, detail="Unauthenticated")
    return user_id


app = FastAPI()


@app.post("/chatkit")
async def chatkit_endpoint(request: Request, user_id: str = Depends(current_user)) -> Response:
    context = RequestContext(user_id=user_id, locale=request.headers.get("accept-language", "fr"))
    try:
        result = await server.process(await request.body(), context)
    except NotFoundError:
        raise HTTPException(status_code=404, detail="Not found")
    if isinstance(result, StreamingResult):
        return StreamingResponse(result, media_type="text/event-stream")
    return Response(content=result.json, media_type="application/json")

Každý uživatel má své vlastní konverzace

Autentizace nestačí: potřebuješ také autorizaci. Bez kontroly by uživatel, který uhodne ID vlákna, mohl číst cizí konverzaci. Správným místem pro tuto kontrolu je úložiště (store), kterým prochází všechny operace čtení. V tomto příkladu si každé vlákno uchovává jméno svého vlastníka ve svých metadatech, která SDK nikdy nepřenáší do rozhraní:

from chatkit.store import NotFoundError
from chatkit.types import Page, ThreadMetadata

from memory_store import MemoryStore


class UserStore(MemoryStore):
    async def save_thread(self, thread: ThreadMetadata, context: RequestContext) -> None:
        thread.metadata.setdefault("owner", context.user_id)
        await super().save_thread(thread, context)

    async def load_thread(self, thread_id: str, context: RequestContext) -> ThreadMetadata:
        thread = await super().load_thread(thread_id, context)
        if thread.metadata.get("owner") != context.user_id:
            raise NotFoundError(f"Thread {thread_id} not found")  # neodhaluj, že existuje
        return thread

    async def load_threads(self, limit, after, order, context: RequestContext) -> Page[ThreadMetadata]:
        page = await super().load_threads(limit, after, order, context)
        page.data = [t for t in page.data if t.metadata.get("owner") == context.user_id]
        return page

Blok try v koncovém bodě (endpoint) zde dává smysl: bez něj by přímé čtení cizího vlákna skončilo chybou 500 místo 404; u streamovaného požadavku, jako je přidání zprávy, SDK přeruší stream bez odeslání čehokoli. V produkci se toto filtrování děje přímo v SQL dotazu (klauzule WHERE owner = … také správně řeší stránkování). Stejné pravidlo aplikuj na přílohy. Dokumentace také připomíná, abys rozhodl, co uchováváš a jak dlouho: vlákna obsahují text, soubory a výsledky nástrojů, tedy často osobní údaje.

Poskytni modelu kontext své aplikace

Model nic neví o stránce, kterou uživatel sleduje, o jeho předplatném nebo otevřeném dokumentu. Dokumentace navrhuje tři způsoby, jak ho to naučit:

  • Při každém požadavku prostřednictvím hlaviček přidaných v api.fetch (X-Page, X-Plan…), které server uloží do kontextu;
  • Na vyžádání prostřednictvím serverového nástroje, který čte ctx.context.request_context a získá informace;
  • V prohlížeči prostřednictvím klientského nástroje, když informace existují pouze tam (viz další sekce).

Jedna opatrnost převzatá z průvodce pro produkci: nikdy nestavěj systémové instrukce modelu z hodnot, které pocházejí od uživatele, ani nepřímo (název vlákna, předmět ticketu). Nech je pevné a proměnný kontext předávej jako data.

Klientské nástroje

Některé informace žijí pouze v prohlížeči: výběr v editoru, stav plátna, neuložený koncept. Klientský nástroj umožňuje modelu požádat o ně uprostřed odpovědi: tvůj server pozastaví agenta, ChatKit provede tvou funkci v prohlížeči a poté vrátí výsledek serveru, který pokračuje.

Na straně serveru nástroj pouze vytvoří požadavek a agent se na něm zastaví:

from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall


@function_tool(description_override="Reads the text the user has selected on the page.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
    ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})


assistant = Agent[AgentContext](
    name="Writing Assistant",
    instructions="Help the user improve the text they select.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

Na straně rozhraní onClientTool přijme požadavek; název se musí shodovat a vrácený objekt putuje na server:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Na jedno kolo může být spuštěn pouze jeden klientský nástroj. A když neočekáváš odpověď, upřednostni efekt: server emituje ClientEffectEvent(name="refresh_cart", data={...}) z respond, action nebo nástroje přes ctx.context.stream(...) a rozhraní jej přijme v onEffect bez přerušení odpovědi. Efekty se nezaznamenávají do vlákna.

Řiď ChatKit ze své aplikace

useChatKit vrací kromě control také metody pro ovládání rozhraní ze zbytku tvého kódu:

MetodaEfekt
sendUserMessage({ text })Odešle zprávu, jako by ji uživatel napsal
setComposerValue({ text })Předvyplní vstupní oblast bez odeslání
setThreadId(id)Otevře existující vlákno nebo nové vlákno s null
focusComposer()Umístí kurzor do vstupní oblasti
showHistory(), hideHistory()Otevře nebo zavře historii konverzací
sendCustomAction(action)Odešle akci na server (Lekce 20)
fetchUpdates()Znovu načte vlákno ze serveru

Tlačítko „Zeptat se asistenta“ na listu produktu se stane jedním řádkem kódu:

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

export function ProductSheet({ product }: { product: string }) {
  const chatkit = useChatKit({ api: { url: '/chatkit', domainKey: 'local-dev' } });

  return (
    <>
      <button onClick={() => chatkit.sendUserMessage({ text: `Is the ${product} product compatible with my equipment?` })}>
        Ask the assistant
      </button>
      <ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
    </>
  );
}

Možnost initialThread otevře při načtení konkrétní vlákno, například to, které uživatel nechal otevřené; s hodnotou null (výchozí hodnota) ChatKit zobrazí domovskou obrazovku.

Sleduj, co se děje

ChatKit emituje události: připravenost (onReady), začátek a konec odpovědi (onResponseStart, onResponseEnd), změnu vlákna (onThreadChange), logy (onLog) a chyby (onError). V Reactu jsou to možnosti pro useChatKit:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onThreadChange: ({ threadId }) => rememberLastThread(threadId),
  onError: ({ error }) => sendTelemetry({ name: 'chatkit.error', message: error.message }),
  onLog: ({ name }) => sendTelemetry({ name: name }),
});

Průvodce pro produkci trvá na jednom bodě: tyto události mohou obsahovat osobní údaje a text zpráv. Neposílej veškerý obsah do svého nástroje pro sledování: extrahuj užitečná pole (název události, ID vlákna, kód chyby). Na straně serveru loguj každý požadavek na /chatkit, volání úložiště a modelu a chyby nástrojů, včetně ID uživatele a vlákna, abys mohl korelovat obě strany.

U pomalých nástrojů udržuj uživatele informovaného: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) zobrazí okamžitý postup, který je nahrazen zbytkem odpovědi a nikdy se nezaznamená do vlákna.

Než přejdeš do produkce

Kontrolní seznam převzatý z oficiálního průvodce:

  • Domény: každý produkční hostname je uveden na stránce Domain allowlist platformy OpenAI a jeho klíč je v domainKey;
  • Autentizace a autorizace: každý požadavek na /chatkit je autentizován, vlákna a přílohy jsou filtrovány podle uživatele;
  • Tajemství: API klíč a interní pověření jsou v proměnných prostředí nebo ve správci tajemství, nikdy v repozitáři;
  • Vstupy: zprávy, soubory, datové náklady akcí a výsledky nástrojů jsou považovány za nedůvěryhodné a před dosažením do tvých systémů validovány;
  • Osobní údaje: doba uchování rozhodnuta a aplikována v úložišti, šifrování v klidu, žádná zbytečná data v metadatech;
  • Jazyk: jazyk v Accept-Language řídí odpovědi agenta i zprávy tvých nástrojů;
  • Sledování: události rozhraní a servery logy sbírány, ale bez citlivého obsahu.

Klíčové poznatky

  • Identita uživatele prochází přes api.fetch na straně rozhraní a poté přes kontext server.process, který ji šíří všude
  • Autorizace probíhá v úložišti: každé vlákno patří uživateli a vlákno jiného uživatele je „nenalezeno“
  • Kontext aplikace přichází přes hlavičky, serverové nástroje nebo klientské nástroje (onClientTool + StopAtTools); efekty (onEffect) slouží, když se neočekává odpověď
  • Metody z useChatKit (sendUserMessage, setThreadId, setComposerValue…) ovládají ChatKit ze zbytku aplikace
  • Události (onError, onLog…) krmí tvé sledování, aniž by do něj kopírovaly osobní údaje; kontrolní seznam pro produkci pokrývá domény, práva, tajemství, vstupy a data