Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Integrazzjoni avvanzata fl-app tiegħek

Lezzjoni 21 / 25 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. X’jifdal wara d-demo
  2. Awtentika kull talba
  3. Kull utent jikseb il-konversazzjonijiet tiegħu stess
  4. Agħti lill-mudell il-kuntest tal-app tiegħek
  5. Għodod fuq in-naħa tal-klijent
  6. Mexxi lil ChatKit mill-applikazzjoni tiegħek
  7. Osserva x’qed jiġri
  8. Qabel ma tmur fil-produzzjoni
  9. Punti Ewlenin

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 SDK openai-chatkit 1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) u t-tipi @openai/chatkit-react 1.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_context u 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:

MetoduEffett
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 /chatkit hija 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-Language tmexxi 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.fetch fuq 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