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

ChatKit: Ħarsa ġenerali u installazzjoni

Lezzjoni 17 / 25 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Għaliex ChatKit
  2. Żewġ modi biex tħaddmu
  3. L-arkitettura fi tliet partijiet
  4. Installazzjoni
  5. Is-server minimu
  6. L-interfaċċa React
  7. Mingħajr React
  8. Sigurtà mill-ewwel jum
  9. Jekk diġà għandek fluss ta’ xogħol ta’ Agent Builder
  10. Punti Ewlenin

Lezzjoni miktuba mill-ġdid fit-3 ta’ Novembru 2026. Il-verżjoni preċedenti kienet tiddeskrivi API li ma teżistix aktar: oġġett new ChatKit({ apiKey, agentId }), komponenti ChatProvider, ChatWindow, u MessageInput, modulu @openai/chatkit/react, u skript cdn.openai.com/chatkit/…. Din il-lezzjoni issa ssegwi l-gwidi uffiċjali ta’ OpenAI ChatKit, l-SDK tal-Python openai-chatkit 1.6.5, u @openai/chatkit-react 1.6.1. Ħejjejna s-server tal-eżempju lokalment biex nivverifikaw kull pass. Nota: Agent Builder jingħalaq fit-30 ta’ Novembru 2026; ChatKit jibqa’ disponibbli. Sorsi: ChatKit · Integrazzjonijiet avvanzati ma’ ChatKit · Bidu rapidu tal-SDK tal-Python · App tal-bidu uffiċjali.

Għaliex ChatKit

Ibnejt aġent bl-SDK tal-Aġenti. Dan jaħdem fit-terminal tiegħek, u ħadd ieħor ma jista’ jużah. Biex tqiegħdu f’idejn l-utenti tiegħek, għandek bżonn interfaċċa ta’ konversazzjoni—u li tibni UI tajba ta’ chat mill-bidu huwa għali. Trid tittratta l-iskrolljar, il-messaġġi streaming, ir-ripristinar tal-konversazzjoni, l-attachments, id-display tas-sejħiet tal-għodod, u l-immaniġġjar tal-iżbalji tan-netwerk.

ChatKit hija t-tweġiba ta’ OpenAI: komponent ta’ konversazzjoni li tintegra fil-prodott tiegħek u li jimmaniġġja l-esperjenza kollha tal-utent. Id-dokumentazzjoni tenfasizza l-widgets interattivi tiegħu, is-suġġerimenti tal-bidu, id-display tas-sejħiet tal-għodod, l-attachments, u l-viżwalizzazzjoni tar-raġunar tal-aġent. Int iżżomm il-kontroll fuq dak li jimpurtak: l-aġent, id-data tiegħek, u r-regoli tiegħek.

Żewġ modi biex tħaddmu

ChatKit hija sempliċiment interfaċċa. Għandha bżonn server li jirċievi l-messaġġi, iħaddem l-aġent, u jibgħat lura r-risposta b’mod streaming. OpenAI tiddeskrivi żewġ approċċi:

TriqKif taħdemGħal min hija
Is-server ChatKit tiegħek stess (integrazzjoni avvanzata)Is-server tal-Python tiegħek, bl-użu tal-SDK openai-chatkit, jirċievi t-talbiet mill-UI u jħaddem l-aġent tal-għażla tiegħek, bħal aġent tal-SDK tal-AġentiKwalunkwe proġett ġdid: din hija t-triq li tirrakkomanda OpenAI
Fluss ta’ xogħol ospitat ta’ Agent BuilderOpenAI tħaddem fluss ta’ xogħol iddisinjat f’Agent Builder; is-server tiegħek joħloq biss is-sessjonijietIntegrazzjonijiet eżistenti matul il-perjodu ta’ tranżizzjoni: Agent Builder jingħalaq fit-30 ta’ Novembru 2026

Dan il-kors isegwi l-ewwel triq—l-unika waħda b’futur. Nagħmlu sommarju tat-tieni waħda fl-aħħar tal-lezzjoni għal dawk li jeħtieġu jżommu integrazzjoni eżistenti sal-għeluq.

L-arkitettura fi tliet partijiet

Integrazzjoni ta’ ChatKit tinżel għal tliet elementi. Li tagħmilhom distinzjoni tevita l-biċċa l-kbira tal-iżbalji tal-bidu:

  1. ChatKit.js, il-komponent innifsu: komponent web <openai-chatkit> li juri l-konversazzjoni f’iframe. Jitgħabba mill-CDN ta’ OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), mhux minn npm: il-pakkett npm @openai/chatkit fih biss id-definizzjonijiet tat-tip tiegħu.
  2. Bindings għal React, @openai/chatkit-react, li jesponu l-komponent ChatKit u l-hook useChatKit. Dawn huma opzjonali: mingħajr React, tikkontrolla l-komponent web direttament.
  3. Is-server ChatKit tiegħek, endpoint HTTP wieħed, konvenzjonalment /chatkit, li jirċievi t-talbiet kollha mill-interfaċċa. Istanza ChatKitServer tirrotjahom, tiddependi fuq maħżen (store) biex jippersista l-filamenti tal-konversazzjoni, u tħaddem l-aġent tiegħek.

Iċ-ċavetta tal-API ta’ OpenAI qatt ma toħroġ mis-server: l-interfaċċa titkellem biss mal-endpoint /chatkit tiegħek.

Installazzjoni

Fuq in-naħa tal-interfaċċa, installa l-bindings ta’ React u tgħabbi l-iskript ChatKit fil-paġna tiegħek:

npm install @openai/chatkit-react
<!-- Fil-<head> tal-paġna tiegħek -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

Fuq in-naħa tas-server, installa l-SDK tal-Python ta’ ChatKit (Python 3.10 jew aktar tard), li jġib miegħu l-SDK tal-Aġenti, flimkien ma’ server web:

pip install openai-chatkit fastapi uvicorn

Is-server minimu

Is-server hawn taħt isegwi l-bidu rapidu uffiċjali. ChatKitServer teħtieġ metodu wieħed biss, respond, imsejjaħ għal kull messaġġ tal-utent. Jerġa’ jgħabbi l-aħħar oġġetti tal-filament, jikkonvertihom f’input tal-aġent b’simple_to_agent_input, iħaddem l-aġent f’modalità streaming, u jittraduċi dak l-istream f’avvenimenti ChatKit b’stream_agent_response:

# main.py
from typing import Any, AsyncIterator

from agents import Agent, Runner
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse

from memory_store import MemoryStore  # maħżen fil-memorja mill-app tal-bidu

assistant = Agent[AgentContext[dict[str, Any]]](
    name="Product Assistant",
    instructions="You help product users. Respond in English, briefly.",
    model="gpt-6.1-sol",
)


class MyChatKitServer(ChatKitServer[dict[str, Any]]):
    async def respond(
        self,
        thread: ThreadMetadata,
        input_user_message: UserMessageItem | None,
        context: dict[str, Any],
    ) -> AsyncIterator[ThreadStreamEvent]:
        # L-aħħar 30 oġġett tal-filament, ripristinati f'ordni kronoloġika
        page = await self.store.load_thread_items(
            thread.id, after=None, limit=30, order="desc", context=context
        )
        agent_input = await simple_to_agent_input(list(reversed(page.data)))
        agent_context = AgentContext(thread=thread, store=self.store, request_context=context)
        result = Runner.run_streamed(assistant, agent_input, context=agent_context)
        async for event in stream_agent_response(agent_context, result):
            yield event


app = FastAPI()
server = MyChatKitServer(MemoryStore())


@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
    result = await server.process(await request.body(), {})
    if isinstance(result, StreamingResult):
        return StreamingResponse(result, media_type="text/event-stream")
    return Response(content=result.json, media_type="application/json")

Ħaddmu b’OPENAI_API_KEY fl-ambjent tiegħek: uvicorn main:app --port 8000.

Il-maħżen (store) jistħoqqilu żewġ kelmiet. ChatKit ma jaħżen xejn waħdu: il-filamenti, il-messaġġi, il-widgets, u s-sejħiet tal-għodod jiġu ppersistiti minn klassi li tirrenja minn chatkit.store.Store u timplimenta madwar dożżina ta’ metodi (load_thread, save_thread, load_thread_items, add_thread_item…). Biex tibda, uża mill-ġdid il-fajl memory_store.py mill-app uffiċjali tal-bidu: iżomm kollox fil-memorja waqt li l-proċess ikun għaddej. Fil-produzzjoni, ibdlu b’database. Id-dokumentazzjoni tirrakkomanda li toħżen l-oġġetti bħala JSON sabiex l-aġġornamenti tal-SDK ma jfurzawx migrazzjonijiet tal-iskema fuqek.

L-interfaċċa React

Fuq in-naħa tal-interfaċċa, useChatKit tirċievi l-konfigurazzjoni u tirritorna oġġett control, li tgħaddih lill-komponent ChatKit:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function Assistant() {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      // Fl-iżvilupp, valur placeholder huwa biżżejjed; fil-produzzjoni,
      // uża ċ-ċavetta tad-dominju tiegħek (ara hawn taħt)
      domainKey: 'local-dev',
    },
  });

  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}

Isservi l-interfaċċa u /chatkit mill-istess oriġini: fl-iżvilupp, il-proxy tal-għodda tal-bini tiegħek tittratta dan (l-app tal-bidu tikkonfigura l-proxy ta’ Vite biex tirridireġi /chatkit lejn il-port 8000). Jekk is-server jgħix fuq oriġini differenti, ippermettih b’mod espliċitu, pereżempju bil-CORSMiddleware ta’ FastAPI.

Mingħajr React

Sit WordPress, applikazzjoni Rails, jew paġna statika tista’ tintegra l-istess assistent: il-komponent web jaħdem direttament ladarba jitgħabba l-iskript CDN.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
  </head>
  <body>
    <div id="chat-root" style="height: 600px"></div>
    <script>
      const chatkit = document.createElement('openai-chatkit');
      chatkit.setOptions({
        api: { url: '/chatkit', domainKey: 'local-dev' },
      });
      document.getElementById('chat-root').append(chatkit);
    </script>
  </body>
</html>

Kull għażla li se tara fil-lezzjonijiet li ġejjin għandha l-istess forma f’żewġ każijiet: oġġett mgħoddi lil useChatKit f’React, jew lil setOptions fuq il-komponent web.

Sigurtà mill-ewwel jum

Tliet regoli, meħuda mill-gwida tal-produzzjoni ta’ ChatKit, japplikaw mill-fażi tal-prototip:

  • Iċ-ċavetta tal-API tibqa’ fuq is-server. M’għandhiex tidher fil-kodiċi tal-interfaċċa jew fir-repożitorju tiegħek: aqraha minn varjabbli tal-ambjent jew minn maniġer tas-sigrieti.
  • Awtentika kull talba lejn /chatkit. L-SDK ma jittrattax dan: l-applikazzjoni tiegħek trid tivverifika s-sessjoni jew it-token tal-utent, imbagħad tgħaddi l-identità tiegħu lil server.process fil-kuntest (lezzjoni 21). Mingħajr dan, kulħadd jista’ jħaddem l-aġent tiegħek bl-ispejjeż tiegħek.
  • Irreġistra d-dominji tiegħek. Qabel ma tmur live, iddikjara kull isem ta’ host li se juri ChatKit fil-paġna Domain allowlist tal-pjattaforma OpenAI, u kkopja ċ-ċavetta ġġenerata f’domainKey. Meta jitgħabba, l-iframe ta’ ChatKit jivverifika din iċ-ċavetta ma’ OpenAI u jirrifjuta li juri jekk tkun nieqsa jew ma taqbilx.

Jekk diġà għandek fluss ta’ xogħol ta’ Agent Builder

Integrazzjonijiet eżistenti marbuta ma’ fluss ta’ xogħol ospitat jaħdmu sakemm jingħalaq Agent Builder. Il-prinċipju tagħhom huwa differenti: is-server tiegħek joħloq sessjoni ChatKit billi jsejjaħ POST https://api.openai.com/v1/chatkit/sessions, bl-header OpenAI-Beta: chatkit_beta=v1, l-ID tal-fluss ta’ xogħol, u identifikatur user uniku għal kull utent awtentikat. Imbagħad jirritorna s-client_secret miksub lill-interfaċċa. Fuq in-naħa tal-interfaċċa, l-għażla api tieħu mbagħad funzjoni getClientSecret minflok URL.

Tibdiex proġett ġdid fuq dan il-mudell. Għal integrazzjoni eżistenti, esporta l-fluss ta’ xogħol f’kodiċi tal-SDK tal-Aġenti u ibdel għas-server ChatKit tiegħek stess qabel it-30 ta’ Novembru 2026, issegwi l-gwida Migrate from Agent Builder.

Punti Ewlenin

  • ChatKit hija interfaċċa ta’ konversazzjoni lesta biex tiġi integrata; is-server tiegħek iħaddem l-aġent
  • Għal kwalunkwe proġett ġdid: is-server ChatKit tiegħek stess (pip install openai-chatkit), b’metodu respond u endpoint /chatkit; Agent Builder ospitat jingħalaq fit-30 ta’ Novembru 2026
  • L-interfaċċa titgħabba mill-CDN ta’ OpenAI; f’React, uża useChatKit u <ChatKit control={control} /> minn @openai/chatkit-react
  • Il-maħżen (store) jippersista l-filamenti tal-konversazzjoni: fil-memorja għall-ittestjar, f’database għall-produzzjoni
  • Ċavetta tal-API biss fuq is-server, /chatkit awtentikat, dominji rreġistrati biex tikseb id-domainKey