Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Napredna integracija u tvoju aplikaciju

Lekcija 21 od 25 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Što preostaje nakon demo verzije
  2. Autenticiraj svaki zahtjev
  3. Svaki korisnik ima svoje razgovore
  4. Daj modelu kontekst svoje aplikacije
  5. Klijentski alati
  6. Upravljaj ChatKitom iz svoje aplikacije
  7. Promatraj što se događa
  8. Prije odlaska u proizvodnju
  9. Ključne točke

Lekcija je ponovno napisana 3. studenoga 2026. Prethodna verzija oslanjala se na izmišljena svojstva i događaje (ChatProvider, način rada „sidebar“, trajnost temeljena na korisničkom sučelju). Sada slijedi vodiče za Python SDK openai-chatkit 1.6.5 (Pripremi svoju aplikaciju za proizvodnju, Proslijedi dodatni kontekst aplikacije, Ažuriraj klijenta tijekom odgovora) i tipove @openai/chatkit-react 1.6.1: serverski kod je izvršen lokalno, a React kod verificiran kompilacijom. Izvori: Pripremi svoju aplikaciju za proizvodnju · Proslijedi dodatni kontekst aplikacije svom modelu · Ažuriraj klijenta tijekom odgovora · Napredne integracije s ChatKitom.

Što preostaje nakon demo verzije

Prethodne četiri lekcije dale su ti funkcionalnog asistenta. Da bi on zaživio u stvarnom proizvodu, treba mu ono što razlikuje demo od usluge: znanje o tome tko govori, prikazivanje razgovora samo svakom pojedinačnom korisniku, interakcija s ostatkom aplikacije i mogućnost promatranja rada (observability). Ova lekcija obrađuje te točke jednu po jednu.

Autenticiraj svaki zahtjev

SDK ne preuzima nikakve pretpostavke o tvojoj autentifikaciji: omogućuje ti da verificiraš korisnika, a zatim proslijediš njegov identitet u server.process unutar konteksta zahtjeva. Taj kontekst prati svaki poziv: nalaziš ga u respond, u action, u storeu i u alatima agenta.

Na strani sučelja, opcija api.fetch zamjenjuje funkciju fetch koju koristi ChatKit. Ovdje dodaješ token sesije svoje aplikacije:

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) => {
        // Zadrži zaglavlja koja postavlja ChatKit, zatim dodaj svoja
        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 strani poslužitelja, ovisnost u FastAPI-ju verificira token i gradi kontekst. Jezik sučelja dolazi u zaglavlju Accept-Language, koje ChatKit šalje sa svakim zahtjevom:

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 autentifikacija: sesija, 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")

Svaki korisnik ima svoje razgovore

Autentifikacija nije dovoljna: treba ti i autorizacija. Bez kontrole, korisnik koji pogodi ID niti mogao bi čitati tuđi razgovor. Pravo mjesto za ovu kontrolu je store, kroz koji prolaze sva čitanja. U ovom primjeru, svaka nit čuva ime vlasnika u svojim metapodacima, koje SDK nikada ne prenosi na sučelje:

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 otkrivaj da postoji
        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 u krajnjoj točki ima smisla ovdje: bez njega, izravno čitanje tuđe niti završilo bi pogreškom 500 umjesto 404; kod zahtjeva s prijenosom podataka (streaming), poput dodavanja poruke, SDK prekida tok bez slanja bilo čega. U proizvodnji se ovo filtriranje događa u samom SQL upitu (klauzula WHERE owner = … također ispravno rukuje paginacijom). Primijeni isto pravilo na privitke. Dokumentacija također podsjeća da odlučiš što zadržavaš i koliko dugo: niti sadrže tekst, datoteke i rezultate alata, dakle često osobne podatke.

Daj modelu kontekst svoje aplikacije

Model ne zna ništa o stranici koju korisnik gleda, njegovoj pretplati ili otvorenom dokumentu. Dokumentacija predlaže tri načina da ga poučiš:

  • Pri svakom zahtjevu, putem zaglavlja dodanih u api.fetch (X-Page, X-Plan…), koja poslužitelj pohranjuje u kontekst;
  • Po potrebi, putem serverskog alata koji čita ctx.context.request_context i dohvaća informacije;
  • U pregledniku, putem klijentskog alata, kada informacije postoje samo tamo (vidi sljedeći odjeljak).

Jedan oprez, preuzet iz vodiča za proizvodnju: nikada ne gradi sustavske upute modela od vrijednosti koje dolaze od korisnika, čak ni neizravno (naslov niti, predmet tiketa). Drži ih fiksnima, a promjenjivi kontekst proslijedi kao podatke.

Klijentski alati

Neke informacije žive samo u pregledniku: odabir u uređivaču, stanje platna, nespremljena skica. Klijentski alat omogućuje modelu da ih zatraži usred razgovora: tvoj poslužitelj pauzira agenta, ChatKit izvrši tvoju funkciju u pregledniku, zatim vraća rezultat poslužitelju, koji nastavlja rad.

Na strani poslužitelja, alat samo inicira zahtjev, a agent se zaustavlja na njemu:

from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall


@function_tool(description_override="Čita tekst koji je korisnik odabrao na stranici.")
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="Pomozi korisniku poboljšati tekst koji odabere.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

Na strani sučelja, onClientTool prima zahtjev; naziv se mora podudarati, a vraćeni objekt ide na poslužitelj:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Samo se jedan klijentski alat može izvršiti po okretaju. A kada ne očekuješ odgovor, radije koristi efekt: poslužitelj emitira ClientEffectEvent(name="refresh_cart", data={...}), iz respond, action ili alata putem ctx.context.stream(...), a sučelje ga prima u onEffect bez prekidanja odgovora. Efekti se ne bilježe u niti.

Upravljaj ChatKitom iz svoje aplikacije

useChatKit vraća, uz control, metode za upravljanje sučeljem iz ostatka tvog koda:

MetodaUčinak
sendUserMessage({ text })Šalje poruku kao da ju je korisnik utipkao
setComposerValue({ text })Unaprijed ispunjava područje za unos bez slanja
setThreadId(id)Otvara postojeću nit, ili novu nit s null
focusComposer()Postavlja kursor u područje za unos
showHistory(), hideHistory()Otvara ili zatvara povijest razgovora
sendCustomAction(action)Šalje radnju na poslužitelj (Lekcija 20)
fetchUpdates()Ponovno učitava nit s poslužitelja

Gumb „Pitaj asistenta“ na listingu proizvoda postaje jedan redak koda:

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: `Je li proizvod ${product} kompatibilan s mojom opremom?` })}>
        Pitaj asistenta
      </button>
      <ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
    </>
  );
}

Opcija initialThread otvara određenu nit pri pokretanju, na primjer onu koju je korisnik ostavio otvorenom; s null (zadana vrijednost), ChatKit prikazuje početni zaslon.

Promatraj što se događa

ChatKit emitira događaje: spreman (onReady), početak i kraj odgovora (onResponseStart, onResponseEnd), promjena niti (onThreadChange), zapisi (onLog) i pogreške (onError). U Reactu su to opcije za 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 }),
});

Vodič za proizvodnju inzistira na jednoj točki: ovi događaji mogu sadržavati osobne podatke i tekst poruka. Ne šalji sav sadržaj u svoj alat za praćenje: izdvoj korisna polja (naziv događaja, ID niti, kod pogreške). Na strani poslužitelja bilježi svaki zahtjev na /chatkit, pozive storeu i modelu te pogreške alata, s ID-om korisnika i niti, kako bi mogao povezati obje strane.

Za spore alate, obavijesti korisnika: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Pretražujem tvoje narudžbe…")) prikazuje trenutni napredak, koji se zamjenjuje ostatkom odgovora i nikada se ne bilježi u niti.

Prije odlaska u proizvodnju

Popis za provjeru, preuzet iz službenog vodiča:

  • Domena: svako produkcijsko ime hosta navedeno je na stranici Domain allowlist platforme OpenAI, a njegov ključ je u domainKey;
  • Autentifikacija i autorizacija: svaki zahtjev na /chatkit je autentificiran, niti i privitci su filtrirani po korisniku;
  • Tajne: API ključ i interne vjerodajnice su u varijablama okruženja ili upravitelju tajni, nikada u repozitoriju;
  • Unosi: poruke, datoteke, tereti radnji i rezultati alata tretiraju se kao nepouzdani i validiraju se prije nego što dosegnu tvoje sustave;
  • Osobni podaci: razdoblje zadržavanja odlučeno i primijenjeno u storeu, šifriranje u mirovanju, nema nepotrebnih podataka u metapodacima;
  • Jezik: jezik iz Accept-Language upravlja odgovorima agenta i porukama tvojih alata;
  • Praćenje: događaji sučelja i serverski zapisi prikupljeni, bez osjetljivog sadržaja.

Ključne točke

  • Identitet korisnika prolazi putem api.fetch na strani sučelja, zatim putem konteksta server.process, koji ga propagira svugdje
  • Autorizacija se događa u storeu: svaka nit pripada korisniku, a nit drugog korisnika je „nije pronađena“
  • Kontekst aplikacije dolazi putem zaglavlja, serverskih alata ili klijentskih alata (onClientTool + StopAtTools); efekti (onEffect) služe kada se ne očekuje odgovor
  • Metode iz useChatKit (sendUserMessage, setThreadId, setComposerValue…) upravljaju ChatKitom iz ostatka aplikacije
  • Događaji (onError, onLog…) hrane tvoje praćenje, bez kopiranja osobnih podataka u njega; popis za proizvodnju pokriva domene, prava, tajne, unose i podatke