Napredna integracija u tvoju aplikaciju
Na ovoj stranici
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 SDKopenai-chatkit1.6.5 (Pripremi svoju aplikaciju za proizvodnju, Proslijedi dodatni kontekst aplikacije, Ažuriraj klijenta tijekom odgovora) i tipove@openai/chatkit-react1.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_contexti 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:
| Metoda | Uč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
/chatkitje 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-Languageupravlja 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.fetchna strani sučelja, zatim putem kontekstaserver.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