Vai al contenuto principale
Italiano— Scegli una lingua
Menu

ChatKit: Panoramica e installazione

Lezione 17 di 25 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché ChatKit
  2. Due modi per alimentarlo
  3. L’architettura a tre pezzi
  4. Installazione
  5. Il server minimale
  6. L’interfaccia React
  7. Senza React
  8. Sicurezza fin dal primo giorno
  9. Se hai già un flusso di lavoro Agent Builder
  10. Punti chiave

Lezione riscritta il 3 novembre 2026. La versione precedente descriveva un’API che non esiste più: un oggetto new ChatKit({ apiKey, agentId }), i componenti ChatProvider, ChatWindow e MessageInput, un modulo @openai/chatkit/react e uno script cdn.openai.com/chatkit/…. Questa lezione segue ora le guide ufficiali di OpenAI ChatKit, la SDK Python openai-chatkit 1.6.5 e @openai/chatkit-react 1.6.1. Abbiamo eseguito il server di esempio in locale per verificare ogni passaggio. Nota: Agent Builder chiuderà il 30 novembre 2026; ChatKit rimarrà disponibile. Fonti: ChatKit · Integrazioni avanzate con ChatKit · Quickstart della SDK Python · App starter ufficiale.

Perché ChatKit

Hai costruito un agente con la SDK Agents. Funziona nel tuo terminale, ma nessun altro può usarlo. Per metterlo nelle mani dei tuoi utenti, hai bisogno di un’interfaccia di conversazione: costruire una buona UI di chat da zero è costoso. Devi gestire lo scorrimento, lo streaming dei messaggi, la ripresa della conversazione, gli allegati, la visualizzazione delle chiamate agli strumenti e la gestione degli errori di rete.

ChatKit è la risposta di OpenAI: un componente di conversazione che incorpori nel tuo prodotto e che gestisce l’intera esperienza utente. La documentazione ne evidenzia i widget interattivi, i suggerimenti iniziali, la visualizzazione delle chiamate agli strumenti, gli allegati e la visualizzazione del ragionamento dell’agente. Tu mantieni il controllo su ciò che conta: l’agente, i tuoi dati e le tue regole.

Due modi per alimentarlo

ChatKit è solo un’interfaccia. Ha bisogno di un server che riceva i messaggi, esegua l’agente e ritorni la risposta in streaming. OpenAI descrive due approcci:

PercorsoCome funzionaA chi è rivolto
Il tuo server ChatKit (integrazione avanzata)Il tuo server Python, usando la SDK openai-chatkit, riceve le richieste dall’UI ed esegue l’agente di tua scelta, come un agente della SDK AgentsQualsiasi nuovo progetto: questo è il percorso raccomandato da OpenAI
Flusso di lavoro Agent Builder ospitatoOpenAI esegue un flusso di lavoro progettato in Agent Builder; il tuo server crea solo le sessioniIntegrazioni esistenti durante il periodo di transizione: Agent Builder chiuderà il 30 novembre 2026

Questo corso segue il primo percorso, l’unico con un futuro. Riassumiamo il secondo alla fine della lezione per chi deve mantenere un’integrazione esistente fino alla chiusura.

L’architettura a tre pezzi

Un’integrazione ChatKit si riduce a tre elementi. Distinguerli evita la maggior parte degli errori da principiante:

  1. ChatKit.js, il componente stesso: un web component <openai-chatkit> che visualizza la conversazione in un iframe. Viene caricato dalla CDN di OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), non da npm: il pacchetto npm @openai/chatkit contiene solo le sue definizioni di tipo.
  2. Binding React, @openai/chatkit-react, che espongono il componente ChatKit e l’hook useChatKit. Sono opzionali: senza React, controlli direttamente il web component.
  3. Il tuo server ChatKit, un singolo endpoint HTTP, convenzionalmente /chatkit, che riceve tutte le richieste dall’interfaccia. Un’istanza ChatKitServer le instrada, si affida a un store per persistere i thread di conversazione ed esegue il tuo agente.

La chiave API di OpenAI non lascia mai il server: l’interfaccia parla solo al tuo endpoint /chatkit.

Installazione

Lato interfaccia, installa i binding React e carica lo script ChatKit nella tua pagina:

npm install @openai/chatkit-react
<!-- Nell'<head> della tua pagina -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>

Lato server, installa la SDK Python di ChatKit (Python 3.10 o successivo), che include la SDK Agents, più un server web:

pip install openai-chatkit fastapi uvicorn

Il server minimale

Il server seguente segue il quickstart ufficiale. ChatKitServer richiede un solo metodo, respond, chiamato per ogni messaggio dell’utente. Ricarica gli ultimi elementi del thread, li converte in input per l’agente con simple_to_agent_input, esegue l’agente in modalità streaming e traduce quello stream in eventi ChatKit con 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  # store in-memory dall'app starter

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]:
        # Gli ultimi 30 elementi del thread, ripristinati in ordine cronologico
        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")

Eseguilo con OPENAI_API_KEY nel tuo ambiente: uvicorn main:app --port 8000.

Lo store merita due parole. ChatKit non memorizza nulla di per sé: thread, messaggi, widget e chiamate agli strumenti sono persistiti da una classe che ereda da chatkit.store.Store e implementa circa una dozzina di metodi (load_thread, save_thread, load_thread_items, add_thread_item…). Per iniziare, riutilizza il file memory_store.py dall’app starter ufficiale: mantiene tutto in memoria mentre il processo è in esecuzione. In produzione, sostituiscilo con un database. La documentazione consiglia di memorizzare gli oggetti come JSON così gli aggiornamenti della SDK non ti forzano a migrazioni dello schema.

L’interfaccia React

Lato interfaccia, useChatKit riceve la configurazione e restituisce un oggetto control, che passi al componente ChatKit:

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

export function Assistant() {
  const { control } = useChatKit({
    api: {
      url: '/chatkit',
      // In sviluppo, un valore segnaposto è sufficiente; in produzione,
      // usa la tua chiave di dominio (vedi sotto)
      domainKey: 'local-dev',
    },
  });

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

Servi l’interfaccia e /chatkit dalla stessa origine: in sviluppo, il proxy del tuo strumento di build se ne occupa (l’app starter configura il proxy di Vite per reindirizzare /chatkit alla porta 8000). Se il server vive su un’origine diversa, consentilo esplicitamente, ad esempio con CORSMiddleware di FastAPI.

Senza React

Un sito WordPress, un’applicazione Rails o una pagina statica possono integrare lo stesso assistente: il web component funziona direttamente una volta caricato lo script 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>

Ogni opzione che vedrai nelle lezioni seguenti ha la stessa forma in entrambi i casi: un oggetto passato a useChatKit in React, o a setOptions sul web component.

Sicurezza fin dal primo giorno

Tre regole, tratte dalla guida alla produzione di ChatKit, si applicano già dalla fase di prototipo:

  • La chiave API rimane sul server. Non deve apparire nel codice dell’interfaccia né nel tuo repository: leggila da una variabile d’ambiente o da un gestore di segreti.
  • Autentica ogni richiesta a /chatkit. La SDK non se ne occupa: la tua applicazione deve verificare la sessione o il token dell’utente, poi passare la sua identità a server.process nel contesto (lezione 21). Senza questo, chiunque può eseguire il tuo agente a tue spese.
  • Registra i tuoi domini. Prima di andare online, dichiara ogni hostname che mostrerà ChatKit sulla pagina Domain allowlist della piattaforma OpenAI e copia la chiave generata in domainKey. Al caricamento, l’iframe di ChatKit verifica questa chiave con OpenAI e si rifiuta di visualizzarsi se manca o non corrisponde.

Se hai già un flusso di lavoro Agent Builder

Le integrazioni esistenti agganciate a un flusso di lavoro ospitato funzionano fino alla chiusura di Agent Builder. Il loro principio differisce: il tuo server crea una sessione ChatKit chiamando POST https://api.openai.com/v1/chatkit/sessions, con l’header OpenAI-Beta: chatkit_beta=v1, l’ID del flusso di lavoro e un identificatore user unico per ogni utente autenticato. Restituisce poi il client_secret ottenuto all’interfaccia. Lato interfaccia, l’opzione api prende allora una funzione getClientSecret invece di un URL.

Non avviare un nuovo progetto su questo modello. Per un’integrazione esistente, esporta il flusso di lavoro in codice Agents SDK e passa al tuo server ChatKit prima del 30 novembre 2026, seguendo la guida Migrate from Agent Builder.

Punti chiave

  • ChatKit è un’interfaccia di conversazione pronta all’integrazione; il tuo server esegue l’agente
  • Per qualsiasi nuovo progetto: il tuo server ChatKit (pip install openai-chatkit), con un metodo respond e un endpoint /chatkit; l’Agent Builder ospitato chiuderà il 30 novembre 2026
  • L’interfaccia si carica dalla CDN di OpenAI; in React, usa useChatKit e <ChatKit control={control} /> da @openai/chatkit-react
  • Lo store persiste i thread di conversazione: in memoria per i test, in un database per la produzione
  • Chiave API solo lato server, /chatkit autenticato, domini registrati per ottenere la domainKey