Salt la conținutul principal
Română— Alege o limbă
Meniu

Integrare avansată în aplicația dumneavoastră

Lecția 21 din 25 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Ce mai rămâne după demonstrație
  2. Autentificați fiecare cerere
  3. Fiecare utilizator are propriile conversații
  4. Oferiți modelului contextul aplicației dumneavoastră
  5. Instrumente lato-client
  6. Comandați ChatKit din aplicația dumneavoastră
  7. Observați ce se întâmplă
  8. Înainte de a trece în producție
  9. Puncte cheie

Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară se baza pe proprietăți și evenimente inventate (ChatProvider, modul „sidebar“, persistență bazată pe interfață). Aceasta urmează acum ghidurile SDK Python openai-chatkit 1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) și tipurile @openai/chatkit-react 1.6.1: codul serverului a fost executat local, iar codul React a fost verificat prin compilare. Surse: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.

Ce mai rămâne după demonstrație

Cele patru lecții anterioare vă oferă un asistent funcțional. Pentru a-l integra într-un produs real, aveți nevoie de elementele care fac diferența dintre o demonstrație și un serviciu: cunoașterea identității interlocutorului, afișarea conversațiilor doar pentru utilizatorul relevant, interacțiunea cu restul aplicației și observabilitatea. Această lecție acoperă aceste puncte, unul câte unul.

Autentificați fiecare cerere

SDK-ul nu face nicio presupunere despre autentificarea dumneavoastră: vă permite să verificați utilizatorul, apoi să transmiteți identitatea acestuia către server.process într-un context de cerere. Acest context însoțește fiecare apel: îl găsiți în respond, în action, în store și în instrumentele agentului.

La nivelul interfeței, opțiunea api.fetch înlocuiește funcția fetch utilizată de ChatKit. Aici adăugați token-ul de sesiune al aplicației dumneavoastră:

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) => {
        // Păstrați anteturile setate de ChatKit, apoi adăugați-le pe ale dumneavoastră
        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]" />;
}

Pe partea de server, o dependență FastAPI verifică token-ul și construiește contextul. Limba interfeței sosește în antetul Accept-Language, pe care ChatKit îl trimite cu fiecare cerere:

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)  # autentificarea dumneavoastră: sesiune, 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")

Fiecare utilizator are propriile conversații

Autentificarea nu este suficientă: aveți nevoie și de autorizare. Fără control, un utilizator care ghicește un ID de thread ar putea citi conversația altcuiva. Locul potrivit pentru acest control este store-ul, prin care trec toate citirile. În acest exemplu, fiecare thread păstrează numele proprietarului în metadatele sale, pe care SDK-ul nu le transmite niciodată interfeței:

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")  # nu dezvăluiți existența acestuia
        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

Blocul try din endpoint are sens aici: fără el, citirea directă a thread-ului altui utilizator s-ar solda cu o eroare 500 în loc de 404; pentru o cerere stream, cum ar fi adăugarea unui mesaj, SDK-ul întrerupe fluxul fără a trimite nimic. În producție, această filtrare are loc chiar în interogarea SQL (un WHERE owner = … gestionează corect și paginarea). Aplicați aceeași regulă și pentru atașamente. Documentația vă reamintește, de asemenea, să decideți ce păstrați și pentru cât timp: thread-urile conțin text, fișiere și rezultate ale instrumentelor, deci adesea date cu caracter personal.

Oferiți modelului contextul aplicației dumneavoastră

Modelul nu știe nimic despre pagina pe care o vizualizează utilizatorul, despre abonamentul său sau despre documentul deschis. Documentația propune trei modalități de a-l informa:

  • La fiecare cerere, prin anteturi adăugate în api.fetch (X-Page, X-Plan…), pe care serverul le stochează în context;
  • La cerere, printr-un instrument de server care citește ctx.context.request_context și preia informațiile;
  • În browser, printr-un instrument lato-client, când informațiile există doar acolo (vezi secțiunea următoare).

O precauție, preluată din ghidul de producție: nu construiți niciodată instrucțiunile de sistem ale modelului din valori care provin de la utilizator, chiar și indirect (titlul thread-ului, subiectul tichetului). Păstrați-le fixe și transmiteți contextul variabil sub formă de date.

Instrumente lato-client

Unele informații există doar în browser: selecția într-un editor, starea canvas-ului, un ciornă nesalvată. Un instrument lato-client permite modelului să le solicite în mijlocul unui tur: serverul dumneavoastră pune agentul în pauză, ChatKit execută funcția în browser, apoi returnează rezultatul serverului, care reia execuția.

Pe partea de server, instrumentul face doar cererea, iar agentul se oprește asupra lui:

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


@function_tool(description_override="Citește textul selectat de utilizator pe pagină.")
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="Ajută utilizatorul să îmbunătățească textul pe care îl selectează.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

La nivelul interfeței, onClientTool primește cererea; numele trebuie să corespundă, iar obiectul returnat merge către server:

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

Doar un singur instrument lato-client poate fi executat per tur. Iar când nu așteptați un răspuns, preferați un efect: serverul emite un ClientEffectEvent(name="refresh_cart", data={...}), din respond, action sau un instrument via ctx.context.stream(...), iar interfața îl primește în onEffect fără a întrerupe răspunsul. Efectele nu sunt înregistrate în thread.

Comandați ChatKit din aplicația dumneavoastră

useChatKit returnează, pe lângă control, metode pentru a comanda interfața din restul codului dumneavoastră:

MetodăEfect
sendUserMessage({ text })Trimite un mesaj ca și cum utilizatorul l-ar fi tastat
setComposerValue({ text })Pre-completează zona de input fără a trimite
setThreadId(id)Deschide un thread existent sau unul nou cu null
focusComposer()Plasează cursorul în zona de input
showHistory(), hideHistory()Deschide sau închide istoricul conversațiilor
sendCustomAction(action)Trimite o acțiune către server (Lecția 20)
fetchUpdates()Reîncarcă thread-ul de la server

Un buton „Întrebați asistentul“ pe o fișă de produs devine o singură linie de cod:

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]" />
    </>
  );
}

Opțiunea initialThread deschide un thread specific la montare, de exemplu cel pe care utilizatorul l-a lăsat deschis; cu null (valoarea implicită), ChatKit afișează ecranul principal.

Observați ce se întâmplă

ChatKit emite evenimente: gata (onReady), început și sfârșit de răspuns (onResponseStart, onResponseEnd), schimbare de thread (onThreadChange), jurnale (onLog) și erori (onError). În React, acestea sunt opțiuni pentru 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 }),
});

Ghidul de producție insistă asupra unui punct: aceste evenimente pot conține date cu caracter personal și textul mesajelor. Nu trimiteți tot conținutul către instrumentul de tracking: extrageți câmpurile utile (numele evenimentului, ID-ul thread-ului, codul erorii). Pe partea de server, jurnalizați fiecare cerere către /chatkit, apelurile către store și model, precum și erorile instrumentelor, cu ID-ul utilizatorului și al thread-ului, pentru a putea corela ambele părți.

Pentru instrumentele lente, mențineți utilizatorul informat: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) afișează un progres imediat, înlocuit de restul răspunsului și neînregistrat niciodată în thread.

Înainte de a trece în producție

Lista de verificare, preluată din ghidul oficial:

  • Domenii: fiecare nume de gazdă de producție este listat pe pagina Domain allowlist din platforma OpenAI, iar cheia sa se află în domainKey;
  • Autentificare și autorizare: fiecare cerere către /chatkit este autentificată, thread-urile și atașamentele sunt filtrate pe utilizator;
  • Secrete: cheia API și credențialele interne se află în variabile de mediu sau într-un manager de secrete, niciodată în repository;
  • Intrări: mesajele, fișierele, sarcinile utile ale acțiunilor și rezultatele instrumentelor sunt tratate ca neconfiabile și validate înainte de a ajunge la sistemele dumneavoastră;
  • Date cu caracter personal: perioada de retenție decisă și aplicată în store, criptare în repaus, fără date inutile în metadate;
  • Limbă: limba din Accept-Language ghidează răspunsurile agentului și mesajele instrumentelor dumneavoastră;
  • Tracking: evenimentele interfeței și jurnalele serverului sunt colectate, fără conținut sensibil.

Puncte cheie

  • Identitatea utilizatorului trece prin api.fetch pe partea de interfață, apoi prin contextul lui server.process, care o propagă peste tot
  • Autorizarea are loc în store: fiecare thread aparține unui utilizator, iar thread-ul altui utilizator apare ca „negăsit“
  • Contextul aplicației sosește prin anteturi, instrumente de server sau instrumente lato-client (onClientTool + StopAtTools); efectele (onEffect) servesc când nu se așteaptă un răspuns
  • Metodele din useChatKit (sendUserMessage, setThreadId, setComposerValue…) comandă ChatKit din restul aplicației
  • Evenimentele (onError, onLog…) alimentează tracking-ul, fără a copia datele personale în acesta; lista de verificare pentru producție acoperă domeniile, drepturile, secretele, intrările și datele