Haladó integráció az alkalmazásodban
Ezen az oldalon
Lecke átírva: 2026. november 3. Az előző verzió kitalált tulajdonságokra és eseményekre épített (
ChatProvider, „oldalsáv“ mód, UI-alapú perzisztencia). Most a Python SDKopenai-chatkit1.6.5 útmutatóit követi (Prepare your app for production, Pass extra app context, Update the client during a response) és az@openai/chatkit-react1.6.1 típusait: a szerverkódot lokálisan lefuttattuk, a React kódot pedig fordítással ellenőriztük. Források: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.
Mi maradt hátra a bemutató után?
Az előző négy lecke egy működő asszisztenst adott a kezedbe. Ahhoz azonban, hogy ez egy valódi termékben éljen, szükség van arra, ami megkülönbözteti a demót a szolgáltatástól: tudnia kell, ki beszél, minden felhasználónak csak a saját beszélgetéseit kell látnia, együtt kell működnie az alkalmazás többi részével, és megfigyelhetőnek kell lennie. Ez a lecke ezeket a pontokat veszi sorra.
Hitelesíts minden kérést
Az SDK nem tesz feltevéseket a hitelesítéseddel kapcsolatban: lehetővé teszi, hogy ellenőrizd a felhasználót, majd az azonosságát egy kérési kontextusban (request context) add át a server.process hívásnak. Ez a kontextus minden hívást követ: megtalálod a respond-ban, az action-ben, a tárolóban (store) és az ügynök eszközeiben is.
A felület oldalán az api.fetch opció helyettesíti a ChatKit által használt fetch függvényt. Itt adhatod hozzá az alkalmazásod munkamenet-tokenjét:
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) => {
// Tartsd meg a ChatKit által beállított fejléceket, majd add hozzá a sajátodat
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]" />;
}
A szerver oldalon egy FastAPI függőség ellenőrzi a tokent és felépíti a kontextust. A felület nyelve az Accept-Language fejlécben érkezik, amelyet a ChatKit minden kéréssel elküld:
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) # a te hitelesítésed: munkamenet, 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")
Minden felhasználónak saját beszélgetései vannak
A hitelesítés önmagában nem elég: jogosultságkezelésre (authorization) is szükség van. Ellenőrzés nélkül egy felhasználó, aki kitalál egy szál azonosítót (thread ID), elolvashatná valaki más beszélgetését. Ennek ellenőrzésének helye a tároló (store), amelyen keresztül minden olvasás áthalad. Ebben a példában minden szál a metaadatai között tárolja a tulajdonos nevét, amit az SDK sosem továbbít a felület felé:
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") # ne áruld el, hogy létezik
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
A végpontban lévő try blokk itt értelmes: enélkül egy másik felhasználó szálának közvetlen olvasása 500-as hibával végződne 404-es helyett; streamelt kérésnél, például üzenet hozzáadásakor, az SDK megszakítja a streamet anélkül, hogy bármit is küldene. Éles környezetben ez a szűrés maga az SQL lekérdezésben történik (egy WHERE owner = … clause a lapozást is helyesen kezeli). Ugyanezt a szabályt alkalmazd a csatolmányokra is. A dokumentáció arra is emlékeztet, hogy döntsd el, mit tartasz meg és meddig: a szálak szöveget, fájlokat és eszközeredményeket tartalmaznak, tehát gyakran személyes adatokat.
Add át az alkalmazás kontextusát a modellnek
A modell nem tud semmit arról az oldalról, amelyet a felhasználó éppen néz, az előfizetéséről vagy a megnyitott dokumentumról. A dokumentáció három módszert javasol ennek megtanítására:
- Minden kéréskor, az
api.fetch-ben hozzáadott fejléceken keresztül (X-Page,X-Plan…), amelyeket a szerver elment a kontextusba; - Igény szerint, egy szerveroldali eszközön keresztül, amely kiolvassa a
ctx.context.request_contextértéket és lekéri az információt; - A böngészőben, egy kliensoldali eszközön keresztül, amikor az információ csak ott létezik (lásd a következő szakaszt).
Egy óvintézkedés, amelyet a production guide emel ki: soha ne építsd fel a modell rendszerutasításait (system instructions) olyan értékekből, amelyek a felhasználótól származnak, még közvetve sem (szál címe, jegy tárgya). Tartsd ezeket fixnek, és a változó kontextust add át adatként.
Kliensoldali eszközök
Egyes információk csak a böngészőben léteznek: kijelölés egy szerkesztőben, vászon állapota, egy nem mentett piszkozat. Egy kliensoldali eszköz lehetővé teszi, hogy a modell kérje ezeket a forduló közepén: a szervered megállítja az ügynököt, a ChatKit lefuttatja a függvényedet a böngészőben, majd visszaadja az eredményt a szervernek, amely folytatja a munkát.
A szerver oldalon az eszköz csak teszi a kérést, és az ügynök megáll rajta:
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]),
)
A felület oldalon az onClientTool fogadja a kérést; a névnek egyeznie kell, és a visszaadott objektum megy vissza a szerverre:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Fordulónként csak egy kliensoldali eszköz hajtható végre. És amikor nem vársz választ, részesítsd előnyben a hatást (effect): a szerver kibocsát egy ClientEffectEvent(name="refresh_cart", data={...}) eseményt a respond, action vagy egy eszköz hívásából a ctx.context.stream(...) segítségével, és a felület az onEffect-ben kapja meg ezt a válasz megszakítása nélkül. A hatások nem kerülnek rögzítésre a szálban.
Vezérld a ChatKitet az alkalmazásodból
A useChatKit a control mellett olyan metódusokat is visszaad, amelyekkel a kód többi részéből irányíthatod a felületet:
| Metódus | Hatás |
|---|---|
sendUserMessage({ text }) | Üzenetet küld, mintha a felhasználó gépelte volna |
setComposerValue({ text }) | Elő tölti a beviteli mezőt küldés nélkül |
setThreadId(id) | Megnyit egy létező szálat, vagy egy újat null értékkel |
focusComposer() | A kurzort a beviteli mezőbe helyezi |
showHistory(), hideHistory() | Megnyitja vagy bezárja a beszélgetések előzményeit |
sendCustomAction(action) | Akciót küld a szervernek (20. lecke) |
fetchUpdates() | Újratölti a szálat a szerverről |
Egy „Kérdezd meg az asszisztenst“ gomb egy termék lapon egyetlen sor kóddá válik:
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]" />
</>
);
}
Az initialThread opció egy konkrét szálat nyit meg betöltéskor, például azt, amelyet a felhasználó nyitva hagyott; null értékkel (ami az alapértelmezett) a ChatKit a kezdőképernyőt jeleníti meg.
Figyeld meg, mi történik
A ChatKit eseményeket bocsát ki: ready (onReady), válasz kezdete és vége (onResponseStart, onResponseEnd), szálváltás (onThreadChange), naplók (onLog) és hibák (onError). Reactben ezek a useChatKit opciói:
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 }),
});
A production guide egy pontra特别 hangsúlyt fektet: ezek az események személyes adatokat és üzenetszöveget tartalmazhatnak. Ne küldj el minden tartalmat a követőeszközödnek: csak a hasznos mezőket emeld ki (esemény neve, szál ID, hiba kód). A szerver oldalon naplózz minden /chatkit kérést, a tároló és a modell hívásait, valamint az eszközhibákat, a felhasználói és szál azonosítókkal együtt, hogy korrelálni tudd a két oldalt.
A lassú eszközöknél tartsd tájékoztatva a felhasználót: az await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) azonnali előrehaladást jelenít meg, amelyet a válasz többi része vált fel, és soha nem rögzül a szálban.
Mielőtt élesbe megy
A hivatalos útmutatóból származó ellenőrzőlista:
- Domainek: minden éles hosztnév szerepel az OpenAI platform Domain allowlist oldalán, és a kulcsa a
domainKey-ben van; - Hitelesítés és jogosultság: minden
/chatkitkérés hitelesített, a szálak és csatolmányok felhasználónként szűrve vannak; - Titkok: az API kulcs és a belső hitelesítő adatok környezetváltozókban vagy titokkezelőben vannak, soha nem a tárolóban;
- Bemenetek: az üzeneteket, fájlokat, akció hasznos adatokat (payloads) és eszközeredményeket megbízhatatlanként kezeljük, és validáljuk, mielőtt elérnék a rendszereidet;
- Személyes adatok: a megőrzési időtartam eldöntve és alkalmazva a tárolóban, titkosítás nyugalmi állapotban, nincs felesleges adat a metaadatokban;
- Nyelv: az
Accept-Languagenyelv vezérli az ügynök válaszait és az eszközüzeneteidet; - Követés: a felületi események és szervernaplók gyűjtve, érzékeny tartalom nélkül.
Főbb megállapítások
- A felhasználó azonossága az
api.fetch-en keresztül jut el a felület oldaláról, majd aserver.processkontextusán át, amely mindenhová továbbítja azt - A jogosultságkezelés a tárolóban történik: minden szál egy felhasználóhoz tartozik, és egy másik felhasználó szála „nem található“-ként jelenik meg
- Az alkalmazás kontextusa fejléceken, szerveroldali eszközökön vagy kliensoldali eszközökön (
onClientTool+StopAtTools) keresztül érkezik; a hatások (onEffect) akkor szolgálnak, amikor nem várt válasz - A
useChatKitmetódusai (sendUserMessage,setThreadId,setComposerValue…) a ChatKitet irányítják az alkalmazás többi részéből - Az események (
onError,onLog…) táplálják a követésedet anélkül, hogy személyes adatokat másolnának bele; a production ellenőrzőlista lefedi a domaineket, jogokat, titkokat, bemeneteket és az adatokat