Pokročilá integrace do vaší aplikace
Na této stránce
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 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 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_contexta 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:
| Metoda | Efekt |
|---|---|
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
/chatkitje 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.fetchna straně rozhraní a poté přes kontextserver.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