Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Integrazione avanzata nella tua app

Lezione 21 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Cosa manca dopo la demo
  2. Autentica ogni richiesta
  3. Ogni utente ha le proprie conversazioni
  4. Dai al modello il contesto della tua app
  5. Strumenti lato client
  6. Guida ChatKit dalla tua applicazione
  7. Osserva cosa sta succedendo
  8. Prima di andare in produzione
  9. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente si basava su proprietà ed eventi inventati (ChatProvider, modalità “sidebar”, persistenza basata sull’interfaccia utente). Ora segue le guide della SDK Python openai-chatkit 1.6.5 (Prepara la tua app per la produzione, Passa contesto aggiuntivo dell’app, Aggiorna il client durante una risposta) e i tipi di @openai/chatkit-react 1.6.1: il codice server è stato eseguito localmente e il codice React verificato tramite compilazione. Fonti: Prepara la tua app per la produzione · Passa contesto aggiuntivo dell’app al tuo modello · Aggiorna il client durante una risposta · Integrazioni avanzate con ChatKit.

Cosa manca dopo la demo

Le precedenti quattro lezioni ti forniscono un assistente funzionante. Per renderlo operativo in un prodotto reale, serve ciò che distingue una demo da un servizio: sapere chi sta parlando, mostrare a ogni utente solo le proprie conversazioni, interagire con il resto dell’applicazione ed essere osservabile. Questa lezione affronta questi punti uno per uno.

Autentica ogni richiesta

La SDK non fa supposizioni sulla tua autenticazione: ti permette di verificare l’utente, per poi passare la sua identità a server.process in un contesto della richiesta. Questo contesto accompagna ogni chiamata: lo trovi in respond, in action, nel store e negli strumenti dell’agente.

Sul lato interfaccia, l’opzione api.fetch sostituisce la funzione fetch usata da ChatKit. È qui che aggiungi il token di sessione della tua applicazione:

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) => {
        // Mantieni le intestazioni impostate da ChatKit, poi aggiungi le nostre
        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]" />;
}

Sul lato server, una dipendenza FastAPI verifica il token e costruisce il contesto. La lingua dell’interfaccia arriva nell’intestazione Accept-Language, che ChatKit invia con ogni richiesta:

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)  # tua autenticazione: sessione, 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")

Ogni utente ha le proprie conversazioni

L’autenticazione non basta: serve anche l’autorizzazione. Senza controllo, un utente che indovina un ID thread potrebbe leggere la conversazione di qualcun altro. Il posto giusto per questo controllo è lo store, attraverso cui passano tutte le letture. In questo esempio, ogni thread mantiene il nome del proprietario nei suoi metadati, che la SDK non trasmette mai all’interfaccia:

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")  # non rivelare che esiste
        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 blocco try nell’endpoint ha senso qui: senza di esso, leggere direttamente il thread di un altro utente finirebbe in un errore 500 invece che in un 404; per una richiesta in streaming, come l’aggiunta di un messaggio, la SDK interrompe lo stream senza inviare nulla. In produzione, questo filtraggio avviene nella query SQL stessa (un WHERE owner = … gestisce correttamente anche la paginazione). Applica la stessa regola agli allegati. La documentazione ricorda anche di decidere cosa conservi e per quanto tempo: i thread contengono testo, file e risultati degli strumenti, quindi spesso dati personali.

Dai al modello il contesto della tua app

Il modello non sa nulla della pagina che l’utente sta visualizzando, del suo abbonamento o del documento aperto. La documentazione propone tre modi per insegnarglielo:

  • A ogni richiesta, tramite intestazioni aggiunte in api.fetch (X-Page, X-Plan…), che il server memorizza nel contesto;
  • Su richiesta, tramite uno strumento server che legge ctx.context.request_context e recupera le informazioni;
  • Nel browser, tramite uno strumento lato client, quando le informazioni esistono solo lì (vedi la sezione successiva).

Una precauzione, tratta dalla guida alla produzione: non costruire mai le istruzioni di sistema del modello partendo da valori che provengono dall’utente, anche indirettamente (titolo del thread, oggetto del ticket). Mantienile fisse e passa il contesto variabile come dati.

Strumenti lato client

Alcune informazioni vivono solo nel browser: selezione in un editor, stato della canvas, una bozza non salvata. Uno strumento lato client permette al modello di richiederle a metà turno: il tuo server mette in pausa l’agente, ChatKit esegue la tua funzione nel browser, poi restituisce il risultato al server, che riprende.

Sul lato server, lo strumento fa solo la richiesta e l’agente si ferma su di essa:

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


@function_tool(description_override="Legge il testo che l'utente ha selezionato sulla pagina.")
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="Aiuta l'utente a migliorare il testo che seleziona.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

Sul lato interfaccia, onClientTool riceve la richiesta; il nome deve corrispondere e l’oggetto restituito va al server:

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

Può essere eseguito un solo strumento lato client per turno. E quando non ti aspetti una risposta, preferisci un effetto: il server emette un ClientEffectEvent(name="refresh_cart", data={...}), da respond, action o uno strumento tramite ctx.context.stream(...), e l’interfaccia lo riceve in onEffect senza interrompere la risposta. Gli effetti non vengono registrati nel thread.

Guida ChatKit dalla tua applicazione

useChatKit restituisce, oltre a control, metodi per comandare l’interfaccia dal resto del tuo codice:

MetodoEffetto
sendUserMessage({ text })Invia un messaggio come se l’utente lo avesse digitato
setComposerValue({ text })Pre-compila l’area di input senza inviare
setThreadId(id)Apre un thread esistente, o un nuovo thread con null
focusComposer()Posiziona il cursore nell’area di input
showHistory(), hideHistory()Apre o chiude la cronologia delle conversazioni
sendCustomAction(action)Invia un’azione al server (Lezione 20)
fetchUpdates()Ricarica il thread dal server

Un pulsante “Chiedi all’assistente” su una scheda prodotto diventa una riga di codice:

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: `Il prodotto ${product} è compatibile con la mia attrezzatura?` })}>
        Chiedi all'assistente
      </button>
      <ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
    </>
  );
}

L’opzione initialThread apre uno specifico thread al montaggio, ad esempio quello che l’utente ha lasciato aperto; con null (il valore predefinito), ChatKit mostra la schermata iniziale.

Osserva cosa sta succedendo

ChatKit emette eventi: pronto (onReady), inizio e fine risposta (onResponseStart, onResponseEnd), cambio thread (onThreadChange), log (onLog) ed errori (onError). In React, queste sono opzioni per 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 }),
});

La guida alla produzione insiste su un punto: questi eventi possono contenere dati personali e testo dei messaggi. Non inviare tutto il contenuto al tuo strumento di tracciamento: estrai i campi utili (nome evento, ID thread, codice errore). Sul lato server, registra ogni richiesta a /chatkit, le chiamate allo store e al modello, e gli errori degli strumenti, con l’ID utente e del thread, così da poter correlare entrambi i lati.

Per strumenti lenti, tieni informato l’utente: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Ricerca dei tuoi ordini…")) mostra un progresso immediato, sostituito dal resto della risposta e mai registrato nel thread.

Prima di andare in produzione

La checklist, tratta dalla guida ufficiale:

  • Domini: ogni hostname di produzione è elencato nella pagina Domain allowlist della piattaforma OpenAI e la sua chiave è in domainKey;
  • Autenticazione e autorizzazione: ogni richiesta a /chatkit è autenticata, thread e allegati sono filtrati per utente;
  • Segreti: la chiave API e le credenziali interne sono in variabili d’ambiente o in un gestore di segreti, mai nel repository;
  • Input: messaggi, file, payload delle azioni e risultati degli strumenti sono trattati come non attendibili e validati prima di raggiungere i tuoi sistemi;
  • Dati personali: periodo di conservazione deciso e applicato nello store, cifratura a riposo, nessun dato non necessario nei metadati;
  • Lingua: la lingua Accept-Language guida le risposte dell’agente e i messaggi dei tuoi strumenti;
  • Tracciamento: eventi dell’interfaccia e log del server raccolti, senza contenuti sensibili.

Punti chiave

  • L’identità dell’utente passa tramite api.fetch sul lato interfaccia, poi tramite il contesto di server.process, che la propaga ovunque
  • L’autorizzazione avviene nello store: ogni thread appartiene a un utente e il thread di un altro utente risulta “non trovato”
  • Il contesto dell’app arriva tramite intestazioni, strumenti server o strumenti lato client (onClientTool + StopAtTools); gli effetti (onEffect) servono quando non è attesa una risposta
  • I metodi di useChatKit (sendUserMessage, setThreadId, setComposerValue…) comandano ChatKit dal resto dell’applicazione
  • Gli eventi (onError, onLog…) alimentano il tuo tracciamento, senza copiarvi dati personali; la checklist per la produzione copre domini, diritti, segreti, input e dati