Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Haladó integráció az alkalmazásodban

21. lecke 25 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Mi maradt hátra a bemutató után?
  2. Hitelesíts minden kérést
  3. Minden felhasználónak saját beszélgetései vannak
  4. Add át az alkalmazás kontextusát a modellnek
  5. Kliensoldali eszközök
  6. Vezérld a ChatKitet az alkalmazásodból
  7. Figyeld meg, mi történik
  8. Mielőtt élesbe megy
  9. Főbb megállapítások

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 SDK openai-chatkit 1.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-react 1.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ódusHatá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 /chatkit ké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-Language nyelv 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 a server.process kontextusá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 useChatKit metó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