Pokročilá integrácia do vašej aplikácie
Na tejto strane
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 SDKopenai-chatkit1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) a typy@openai/chatkit-react1.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_contexta 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óda | Efekt |
|---|---|
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
/chatkitje 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-Languageriadi 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.fetchna strane rozhrania a následne cez kontextserver.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