Integrazzjoni avvanzata fl-app tiegħek
F'din il-paġna
Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru, 2026. Il-verżjoni preċedenti kienet tiddependi fuq proprjetajiet u avvenimenti inventati (
ChatProvider, modalità “sidebar”, persistenza bbażata fuq l-UI). Issa ssegwi l-gwidi tal-Python SDKopenai-chatkit1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) u t-tipi@openai/chatkit-react1.6.1: il-kodiċi tas-server ġie eżegwit lokalment, u l-kodiċi React verifikat permezz tal-kompilazzjoni. Sorsi: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.
X’jifdal wara d-demo
L-erba’ lezzjonijiet preċedenti tawk assistent li jaħdem. Biex tgħix f’prodott reali, jeħtieġ dak li jifred id-demo minn servizz: li jkun jaf min qed jitkellem, li juri lil kull utent il-konversazzjonijiet tiegħu biss, li jinteraġixxi mal-bqija tal-applikazzjoni, u li jkun osservabbli. Din il-lezzjoni tkopri dawn il-punti wieħed wieħed.
Awtentika kull talba
L-SDK ma jagħmel l-ebda preżunzjoni dwar l-awtentikazzjoni tiegħek: iħallik tivverifika l-utent, imbagħad tgħaddi l-identità tiegħu lil server.process f’kuntest ta’ talba. Dan il-kuntest isegwi kull sejħa: issibu f’respond, f’action, fil-store, u fl-għodod tal-aġent.
Fuq in-naħa tal-interfaċċja, l-għażla api.fetch tissostitwixxi l-funzjoni fetch użata minn ChatKit. Hawnhekk iżżid it-token tas-sessjoni tal-applikazzjoni tiegħek:
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) => {
// Żomm l-intestaturi stabbiliti minn ChatKit, imbagħad żid dawk tiegħek
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]" />;
}
Fuq in-naħa tas-server, dipendenza FastAPI tivverifika t-token u tibni l-kuntest. Il-lingwa tal-interfaċċja tasal fl-intestatura Accept-Language, li ChatKit tibgħat ma’ kull talba:
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) # l-awtentikazzjoni tiegħek: sessjoni, 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")
Kull utent jikseb il-konversazzjonijiet tiegħu stess
L-awtentikazzjoni mhix biżżejjed: teħtieġ ukoll awtorizzazzjoni. Mingħajr kontroll, utent li jissuspetta ID ta’ thread jista’ jaqra l-konversazzjoni ta’ ħaddieħor. Il-post it-tajjeb għal dan il-kontroll huwa l-store, li minnu jgħaddu l-qari kollu. F’dan l-eżempju, kull thread iżomm l-isem tas-sid tiegħu fil-metadejta tiegħu, li l-SDK qatt ma jittrażmetti lill-interfaċċja:
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") # tiżvelax li jeżisti
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
Il-blokk try fl-endpoint jagħmel sens hawn: mingħajru, il-qari dirett ta’ thread ta’ utent ieħor jispiċċa f’żball 500 minflok 404; għal talba streamed, bħal żieda ta’ messaġġ, l-SDK jinterrompi l-fluss mingħajr ma jibgħat xejn. Fil-produzzjoni, dan il-filtru jsir fil-mistoqsija SQL innifisha (klawsola WHERE owner = … tittratta wkoll il-paġinazzjoni b’mod korrett). Applika l-istess regola għall-attachments. Id-dokumentazzjoni tfakkrek ukoll biex tiddeċiedi x’tżomm u għal kemm żmien: it-threads fihom test, fajls, u riżultati ta’ għodod, allura spiss data personali.
Agħti lill-mudell il-kuntest tal-app tiegħek
Il-mudell ma jaf xejn dwar il-paġna li qed iħares l-utent, is-sottoskrizzjoni tiegħu, jew id-dokument miftuħ. Id-dokumentazzjoni tipproponi tliet modi biex tgħallmu:
- Fuq kull talba, permezz ta’ intestaturi miżjuda f’
api.fetch(X-Page,X-Plan…), li s-server jaħżen fil-kuntest; - Meta jkun meħtieġ, permezz ta’ għodda tas-server li taqra
ctx.context.request_contextu tiġbed l-informazzjoni; - Fil-browser, permezz ta’ għodda fuq in-naħa tal-klijent, meta l-informazzjoni teżisti biss hemmhekk (ara s-sezzjoni li jmiss).
Prekawzjoni waħda, meħuda mill-gwida tal-produzzjoni: qatt tibni l-istruzzjonijiet tas-sistema tal-mudell minn valuri li ġejjin mill-utent, anke indirettament (titlu tat-thread, suġġett tat-ticket). Żommhom fissi, u għaddi l-kuntest varjabbli bħala data.
Għodod fuq in-naħa tal-klijent
Xi informazzjoni tgħix biss fil-browser: selezzjoni f’editur, stat tal-canva, abbozz mhux maħżun. Għodda fuq in-naħa tal-klijent tippermetti lill-mudell jitlobhom f’nofs it-turn: is-server tiegħek iwaqqaf l-aġent, ChatKit jesegwixxi l-funzjoni tiegħek fil-browser, imbagħad jirritorna r-riżultat lis-server, li jkompli.
Fuq in-naħa tas-server, l-għodda tagħmel it-talba biss, u l-aġent jieqaf fuqha:
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]),
)
Fuq in-naħa tal-interfaċċja, onClientTool tirċievi t-talba; l-isem irid jaqbel, u l-oġġett ritornat imur lis-server:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Għodda waħda biss fuq in-naħa tal-klijent tista’ tesegwixxi kull turn. U meta ma tistennix tweġiba, ippreferi effett: is-server jemetti ClientEffectEvent(name="refresh_cart", data={...}), minn respond, action, jew għodda permezz ta’ ctx.context.stream(...), u l-interfaċċja tirċieviha f’onEffect mingħajr ma tinterrompi t-tweġiba. L-effetti ma jiġux irreġistrati fit-thread.
Mexxi lil ChatKit mill-applikazzjoni tiegħek
useChatKit tirritorna, minbarra control, metodi biex tikkmanda l-interfaċċja mill-bqija tal-kodiċi tiegħek:
| Metodu | Effett |
|---|---|
sendUserMessage({ text }) | Tibgħat messaġġ daqslikieku l-utent ikteb |
setComposerValue({ text }) | Timla minn qabel iż-żona tal-input mingħajr ma tibgħat |
setThreadId(id) | Jiftaħ thread eżistenti, jew thread ġdid b’null |
focusComposer() | Ipoġġi l-kursur fiż-żona tal-input |
showHistory(), hideHistory() | Jiftaħ jew jingħalaq l-istorja tal-konversazzjoni |
sendCustomAction(action) | Tibgħat azzjoni lis-server (Lezzjoni 20) |
fetchUpdates() | Jerġa’ jtagħbija t-thread mis-server |
Buttuna “Staqsi lill-assistent” fuq folja tal-prodott issir linja waħda ta’ kodiċi:
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]" />
</>
);
}
L-għażla initialThread tiftaħ thread speċifiku waqt il-mount, pereżempju dak li l-utent ħalla miftuħ; b’null (il-valur default), ChatKit juri l-iskrin tad-dar.
Osserva x’qed jiġri
ChatKit jemetti avvenimenti: lest (onReady), bidu u tmiem tat-tweġiba (onResponseStart, onResponseEnd), bidla fit-thread (onThreadChange), logs (onLog), u żbalji (onError). F’React, dawn huma għażliet għal 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 }),
});
Il-gwida tal-produzzjoni tinsisti fuq punt wieħed: dawn l-avvenimenti jistgħu jkun fihom data personali u test tal-messaġġi. Tibgħatx il-kontenut kollu lill-għodda tat-traċċar tiegħek: estrai oqsma utli (isem l-avveniment, ID tat-thread, kodiċi tal-iżball). Fuq in-naħa tas-server, irreġistra kull talba lejn /chatkit, sejħiet lis-store u lill-mudell, u żbalji tal-għodod, bl-ID tal-utent u tat-thread, biex tkun tista’ tikkorrelata ż-żewġ naħat.
Għal għodod bil-mod, żomm lill-utent infurmat: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) juri progress immedjat, sostitwit mill-bqija tat-tweġiba u qatt irreġistrat fit-thread.
Qabel ma tmur fil-produzzjoni
Iċ-checklist, meħuda mill-gwida uffiċjali:
- Domanji: kull isem ta’ host tal-produzzjoni huwa elenkat fil-paġna Domain allowlist tal-pjattaforma OpenAI, u ċ-ċavetta tiegħu hija f’
domainKey; - Awtentikazzjoni u awtorizzazzjoni: kull talba lejn
/chatkithija awtentikata, it-threads u l-attachments huma ffiltrati skont l-utent; - Sigrieti: iċ-ċavetta tal-API u l-kredenzjali interni huma f’varjabbli tal-ambjent jew f’maniġer tas-sigrieti, qatt fir-repożitorju;
- Inputs: il-messaġġi, il-fajls, il-payloads tal-azzjoni, u r-riżultati tal-għodod huma ttrattati bħala mhux affidabbli, u vvalidati qabel ma jaslu għas-sistemi tiegħek;
- Data personali: perjodu ta’ ritenzjoni deċiż u applikat fil-store, enkriptazzjoni waqt il-mistrieħ, l-ebda data mhux meħtieġa fil-metadejta;
- Lingwa: il-lingwa
Accept-Languagetmexxi t-tweġibiet tal-aġent u l-messaġġi tal-għodod tiegħek; - Traċċar: avvenimenti tal-interfaċċja u logs tas-server miġbura, mingħajr kontenut sensittiv fihom.
Punti Ewlenin
- L-identità tal-utent tgħaddi permezz ta’
api.fetchfuq in-naħa tal-interfaċċja, imbagħad permezz tal-kuntest ta’server.process, li jxerrdu kullimkien - L-awtorizzazzjoni sseħħ fil-store: kull thread jappartjeni għal utent, u thread ta’ utent ieħor huwa “mhux misjub”
- Il-kuntest tal-app jasal permezz ta’ intestaturi, għodod tas-server, jew għodod fuq in-naħa tal-klijent (
onClientTool+StopAtTools); l-effetti (onEffect) jservu meta ma tkunx mistennija tweġiba - Il-metodi minn
useChatKit(sendUserMessage,setThreadId,setComposerValue…) jikkmandaw lil ChatKit mill-bqija tal-applikazzjoni - L-avvenimenti (
onError,onLog…) jgħaqqdu mat-traċċar tiegħek, mingħajr ma jikkupjaw data personali fih; iċ-checklist tal-produzzjoni tkopri d-domanji, id-drittijiet, is-sigrieti, l-inputs, u d-data