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

Pokročilá integrácia do vašej aplikácie

Lekcia 21 z 25 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Čo zostáva po demoverzii
  2. Autentifikuj každú požiadavku
  3. Každý používateľ má svoje vlastné konverzácie
  4. Poskytni modelu kontext svojej aplikácie
  5. Klientske nástroje
  6. Ovládaj ChatKit zo svojej aplikácie
  7. Sleduj, čo sa deje
  8. Pred nasadením do produkcie
  9. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026. Predchádzajúca verzia sa spoliehala na vymyslené vlastnosti a udalosti (ChatProvider, režim „sidebar“, perzistencia založená na UI). Teraz nasleduje 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 servera bol lokálne spustený a React kód overený kompiláciou. Zdroje: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.

Čo zostáva po demoverzii

Predchádzajúce štyri lekcie ti dali funkčného asistenta. Aby však žil v reálnom produkte, potrebuje to, čo oddeľuje demo od služby: vedieť, kto hovorí, zobrazovať každému používateľovi len jeho konverzácie, interagovať so zvyškom aplikácie a byť pozorovateľný. Táto lekcia pokrýva tieto body jeden po druhom.

Autentifikuj každú požiadavku

SDK nič nepredpokladá o tvojej autentifikácii: umožňuje ti overiť používateľa a potom odovzdať jeho identitu do server.process v kontexte požiadavky. Tento kontext sprevádza každé volanie: nájdeš ho v respond, v action, v úložisku (store) aj v nástrojoch agenta.

Na strane rozhrania možnosť api.fetch nahrádza funkciu fetch, ktorú používa ChatKit. Tu pridáš relačný token svojej aplikácie:

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) => {
        // Zachovaj hlavičky nastavené ChatKitom, potom pridaj 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 strane servera závislosť FastAPI overí token a zostaví kontext. Jazyk rozhrania prichádza v hlavičke Accept-Language, ktorú ChatKit odosiela s každou požiadavkou:

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)  # tvoja autentifikácia: 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ý používateľ má svoje vlastné konverzácie

Autentifikácia nestačí: potrebuješ aj autorizáciu. Bez kontroly by používateľ, ktorý uhádne ID vlákna, mohol čítať cudziu konverzáciu. Správne miesto pre túto kontrolu je úložisko (store), cez ktoré prechádzajú všetky čítania. V tomto príklade si každé vlákno uchováva meno vlastníka vo svojich metadátach, ktoré SDK nikdy neprenáša do rozhrania:

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")  # neodhaľuj, ž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 koncovom bode (endpoint) tu dáva zmysel: bez neho by priame čítanie vlákna iného používateľa skončilo chybou 500 namiesto 404; pri streamovanej požiadavke, ako je pridanie správy, SDK preruší stream bez odoslania čohokoľvek. V produkcii sa toto filtrovanie deje priamo v SQL dotaze (klauzula WHERE owner = … tiež správne rieši stránkovanie). Rovnaké pravidlo aplikuj na prílohy. Dokumentácia tiež pripomína, aby si sa rozhodol, čo uchovávaš a ako dlho: vlákna obsahujú text, súbory a výsledky nástrojov, teda často osobné údaje.

Poskytni modelu kontext svojej aplikácie

Model nič nevie o stránke, ktorú používateľ práve zobrazuje, o jeho predplatnom alebo otvorenom dokumente. Dokumentácia navrhuje tri spôsoby, ako ho to naučiť:

  • Pri každej požiadavke prostredníctvom hlavičiek pridaných v api.fetch (X-Page, X-Plan…), ktoré server uloží do kontextu;
  • Na požiadanie prostredníctvom nástroja na serveri, ktorý číta ctx.context.request_context a získava informácie;
  • V prehliadači prostredníctvom klientskeho nástroja, keď informácie existujú len tam (pozri ďalšiu sekciu).

Jedna opatrnosť prevzatá z návodu pre produkciu: nikdy nebuduj systémové inštrukcie modelu z hodnôt, ktoré pochádzajú od používateľa, ani nepriamo (názov vlákna, predmet tiketu). Nechaj ich pevné a premenlivý kontext odovzdávaj ako dáta.

Klientske nástroje

Niektoré informácie existujú len v prehliadači: výber v editore, stav plátna, neuložený koncept. Klientsky nástroj umožňuje modelu vyžiadať si ich uprostred odpovede: tvoj server pozastaví agenta, ChatKit vykoná tvoju funkciu v prehliadači a potom vráti výsledok serveru, ktorý pokračuje.

Na strane servera nástroj len vytvorí požiadavku a agent sa na nej 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 strane rozhrania onClientTool prijíma požiadavku; názov sa musí zhodovať a vrátený 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 sa môže vykonať iba jeden klientsky nástroj. A keď neočakávaš odpoveď, uprednostni efekt: server vysiela ClientEffectEvent(name="refresh_cart", data={...}) z respond, action alebo nástroja cez ctx.context.stream(...), a rozhranie ho prijíma v onEffect bez prerušenia odpovede. Efekty sa nezaznamenávajú vo vlákne.

Ovládaj ChatKit zo svojej aplikácie

useChatKit vracia okrem control aj metódy na príkazovanie rozhraniu zo zvyšku tvojho kódu:

MetódaEfekt
sendUserMessage({ text })Odošle správu, akoby ju používateľ napísal
setComposerValue({ text })Predvyplní vstupnú oblasť bez odoslania
setThreadId(id)Otvorí existujúce vlákno alebo nové vlákno s hodnotou null
focusComposer()Umiestni kurzor do vstupnej oblasti
showHistory(), hideHistory()Otvorí alebo zavrie históriu konverzácií
sendCustomAction(action)Odošle akciu na server (Lekcia 20)
fetchUpdates()Znovu načíta vlákno zo servera

Tlačidlo „Opýtať sa asistenta“ na liste produktu sa stane jedným riadkom 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žnosť initialThread otvorí pri načítaní konkrétne vlákno, napríklad to, ktoré používateľ nechal otvorené; s hodnotou null (predvolená hodnota) ChatKit zobrazí domovskú obrazovku.

Sleduj, čo sa deje

ChatKit vysiela udalosti: pripravenosť (onReady), začiatok a koniec odpovede (onResponseStart, onResponseEnd), zmenu vlákna (onThreadChange), záznamy (onLog) a chyby (onError). V Reacte sú to možnosti pre 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 }),
});

Návod pre produkciu trvá na jednom bode: tieto udalosti môžu obsahovať osobné údaje a text správ. Neposielaj celý obsah do svojho nástroja na sledovanie: extrahuj užitočné polia (názov udalosti, ID vlákna, kód chyby). Na strane servera loguj každú požiadavku na /chatkit, volania úložiska a modelu a chyby nástrojov spolu s ID používateľa a vlákna, aby si mohol korelovať obe strany.

Pre pomalé nástroje informuj používateľa: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) zobrazí okamžitý postup, ktorý je nahradený zvyškom odpovede a nikdy sa nezaznamená vo vlákne.

Pred nasadením do produkcie

Kontrolný zoznam prevzatý z oficiálneho návodu:

  • Domény: každý produkčný názov hostiteľa je uvedený na stránke Domain allowlist platformy OpenAI a jeho kľúč je v domainKey;
  • Autentifikácia a autorizácia: každá požiadavka na /chatkit je autentifikovaná, vlákna a prílohy sú filtrované podľa používateľa;
  • Tajné údaje: API kľúč a interné poverenia sú v premenných prostredia alebo správcovi tajomstiev, nikdy nie v repozitári;
  • Vstupy: správy, súbory, užitočné zaťaženia akcií a výsledky nástrojov sa považujú za nedôveryhodné a pred dosiahnutím tvojich systémov sa validujú;
  • Osobné údaje: doba uchovávania je rozhodnutá a aplikovaná v úložisku, šifrovanie v pokoji, žiadne zbytočné údaje v metadátach;
  • Jazyk: jazyk v hlavičke Accept-Language riadi odpovede agenta a správy tvojich nástrojov;
  • Sledovanie: udalosti rozhrania a serverové logy sa zbierajú bez citlivého obsahu.

Kľúčové poznatky

  • Identita používateľa prechádza cez api.fetch na strane rozhrania a následne cez kontext server.process, ktorý ju šíri všade
  • Autorizácia sa deje v úložisku: každé vlákno patrí používateľovi a vlákno iného používateľa sa javí ako „nenájdené“
  • Kontext aplikácie prichádza cez hlavičky, serverové nástroje alebo klientske nástroje (onClientTool + StopAtTools); efekty (onEffect) slúžia, keď sa neočakáva odpoveď
  • Metódy z useChatKit (sendUserMessage, setThreadId, setComposerValue…) ovládajú ChatKit zo zvyšku aplikácie
  • Udalosti (onError, onLog…) kŕmia tvoje sledovanie bez kopírovania osobných údajov; kontrolný zoznam pre produkciu pokrýva domény, práva, tajomstvá, vstupy a dáta